Agent Profiles

Agent Profiles describe how a coding agent is presented, selected, authorized, and connected to a runtime adapter. They are the bridge between product UX and execution details.

Profile Model

A useful profile answers five questions:

Question	Example
Who is this agent?	`Codex Local`, `Claude Code Review`, `Mock Writer`
What can it do?	Read files, propose diffs, run commands, produce artifacts
Where can it run?	Local Edge, authorized Remote Edge, or Hub-routed target
What requires approval?	Writes, shell commands, external network, publish actions
Which adapter owns execution?	mock, claude-code, codex, opencode, or custom

Profiles should be small, inspectable, and safe to share after redaction. They should not contain real provider keys, private paths, or production host details.

Public-Safe Shape

Use examples like this in public docs:

JSON

{
  "id": "codex-local-review",
  "label": "Codex Local Review",
  "adapter": "codex",
  "target": "local-edge",
  "workspacePolicy": "allowlist",
  "capabilities": ["read", "diff", "explain", "shell-request"],
  "approval": {
    "write": "ask",
    "shell": "ask",
    "publish": "deny"
  },
  "events": ["run.message.delta", "run.tool.call", "run.diff.ready", "run.approval.requested", "run.completed"]
}

Real implementations may use different file names, storage, or registry APIs while AgentHub converges. The contract that should remain stable is the separation between profile metadata, runtime adapter execution, workspace policy, and approval policy.

Capability Vocabulary

Recommended capability words:

Capability	Meaning
`read`	Can inspect allowlisted files
`diff`	Can propose changes as reviewable diffs
`write-request`	Can request file writes, but not apply silently
`shell-request`	Can request shell commands through approval
`artifact`	Can produce logs, previews, summaries, or files
`review`	Can comment on diffs or documents
`publish`	Can request PR, tag, deploy, or release actions

Avoid vague labels like admin, full-access, or auto. If a profile needs broad power, describe that power explicitly and add a review gate.

Selection Rules

AgentHub should select a profile through explicit user or policy choice:

User selects a workspace or project.
Hub or Desktop lists profiles allowed for that context.
User chooses an agent profile or accepts a safe default.
Edge validates the adapter, workspace allowlist, and runtime availability.
Run events record which profile and adapter were used.

Do not let a Web client silently select a local runtime outside Hub authorization. Do not let Feishu/Lark messages route to Edge until TokenDance ID binding and product authorization have been resolved.

Approval Policy

Profiles should declare approval behavior in plain language:

Action	Safer default
Read allowlisted files	allow
Produce diff	allow
Apply file writes	ask
Run shell command	ask
Access network	ask or deny
Publish PR/tag/deploy	ask or deny
Read outside workspace	deny

The UI should render approval requests with enough context to decide: action, target, reason, risk, and expected output.

Runtime Adapter Boundary

The profile is not the adapter. The adapter owns process execution and event normalization; the profile owns product-facing identity and policy. Keep these responsibilities separate:

Owner	Responsibilities
Profile	Label, icon, capabilities, policy, default target
Adapter	CLI/process invocation, stream parsing, timeout, cancellation, event mapping
Edge	Workspace allowlist, run lifecycle, approval enforcement, artifacts
Hub	User session, project membership, routing, audit

Status

The runtime adapter direction is contract-shaped. Claude Code, Codex, OpenCode, mock, and custom runtime paths may exist in implementation, but a stable public third-party SDK and submission flow are still in development. Related pages: Adapters, Configuration, and Security.