BH Agent Overview

#The Two Surfaces

• Your agent space (/u/<you>/bh-agent/): personal overview, reusable skills, and MCP servers you configure once and grant to agents.
• Project agent tab (/u/<you>/projects/<project>/agent): chat, providers, and skills scoped to one project.

#Connecting to Workflows

step.agent is the workflow primitive that runs an agent with explicitly granted capabilities. The product surfaces above are what it draws on:

• provider.key(...) must reference a key enabled for the project (project agent providers tab); other references fail with an unknown_provider_key diagnostic.
• mcp.server("github") grants a preconfigured MCP connection — credentials live in the MCP server configuration, never in the workflow.
• Context items (agent.context.text/path/artifact/dataset) pass by reference; contents are never injected wholesale into the model.

Full primitive reference: Agents.

#Project Config Behind Agents

Providers, secrets, and MCP connections resolve through project configuration (config.var / config.secret / config.mcp), managed in the project's Vars / Secrets / MCP tabs. See Configuration.

#Specialized Agents (Chat)

Agent chat delegates to specialized subagents (recon, exploit, triage, report) through the task tool. On the project's AI Providers tab you can route each role to its own provider key and model, so cheap work runs on a cheap model while hard work uses a stronger one. Leaving a role's provider or model empty makes it inherit the session's.

Workflow step.agent steps configure the same idea in the workflow source with agent.harness([...]) — see Agents.

#Attaching Project Context

A message can point the agent at data that already exists in the project instead of pasting it into the prompt:

• From a run page: Investigate with agent attaches the whole run, and Ask agent on one artifact attaches that artifact. The agent session opens with the reference ready for you to describe the task.
• From the composer: Attach run, then paste a run link or id. Pasting a run link directly into a message does the same thing.

Attachments travel as bountyhub:// references (bountyhub://run/<id>, bountyhub://run/<id>/artifact/<name>) inside the message text, so they survive compaction, forking, and replay. The agent reads them with the bundled BountyHub MCP tools (get_workflow_run, read_artifact) using its task-scoped token. Contents are never copied into the prompt, and access is still enforced by the platform's scopes: the reference only tells the agent what to look at.

read_artifact extracts the archive into the session workspace under context/runs/<run>/<artifact>/, where the agent's file tools can read it.

#Diagnosing a Session

The session menu (⋯) in the chat header has Copy session. It copies a Markdown report you can paste into an issue or a thread: session id, project, runner, provider/model, state, approval mode, timings, token usage, MCP servers, and the full event log including tool arguments and output (tool output is capped at 20k chars per call). Use it when a session stalls, fails, or behaves differently from what the transcript suggests.

#Next Steps

• MCP servers: Add transports, authenticate with API keys, and grant servers to projects and workflow steps.
• Agents: The complete step.agent reference.
• Projects Overview: Where the agent tab lives.
• Developer Scopes: PAT scopes if you drive agents via the API.