# BH Agent Overview

> Agent chat, skills, providers, and MCP servers — the product surface behind step.agent workflow steps.

## 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:

```bhw
step.agent(
    prompt = "Classify each finding as EXPLOITABLE, LIKELY_NOISE, or OUT_OF_SCOPE.",
    provider = provider.key("anthropic/personal"),
    model = model("default"),
    context = [
        agent.context.path(description = "Findings to triage.", path = path.file("findings.txt")),
    ],
    tools = [tool.shell(), mcp.server("github")],
    output = agent.output(path = path.file("agent-output.txt")),
)
```

- `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](/workflows/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](/workflows/config).

## 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](/workflows/agents#specialized-agents-harness).

## 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](/agent/mcp-servers): Add transports, authenticate with API
keys, and grant servers to projects and workflow steps.
- [Agents](/workflows/agents): The complete `step.agent` reference.
- [Projects Overview](/projects/overview): Where the agent tab lives.
- [Developer Scopes](/developer/scopes): PAT scopes if you drive agents via
the API.