# api_agent_mcp

An MCP server for reusable, role-based agents. It supports **Solo** mode and bounded **Discussion** mode: independent proposals, parallel critique, a separate judge, optional revision rounds, and SQLite session events.

See [dsaa.md](dsaa.md) for the original project vision and architecture notes (Russian).

## Quick start

```bash
uv sync --extra test
export API_AGENT_API_KEY="your-provider-key"
# Optional: OpenAI-compatible endpoint and default model
export API_AGENT_BASE_URL="https://api.openai.com/v1"
export API_AGENT_MODEL="gpt-4o-mini"
uv run api-agent-mcp
```

The server uses stdio transport. Set `API_AGENT_DB` to override the database path; the default is `~/.api_agent_mcp/data.db`. Task text and model responses are stored in the local SQLite event log, so protect or remove that database if it contains sensitive data.

- `API_AGENT_TIMEOUT`: provider request timeout in seconds (default `120`)

## MCP tools

- `create_agent`: add a profile with a name, role, system prompt, optional model and routing tags.
- `update_agent`: update provided profile fields.
- `list_agents`: list configured profiles.
- `run_solo`: run a task with a named agent, or route by matching tags. Ambiguous/no matches return an error instead of silently choosing the wrong profile.
- `run_discussion`: start independent proposals, collect parallel critiques, ask an independent judge for a structured verdict, and revise if the judge reports no consensus.

Profiles are also exposed as `agent://profiles/{name}` resources.

Discussion requires at least two distinct participant profiles and a separate judge profile (pass `judge`, or register a profile with role `judge`). It runs synchronously over MCP stdio and reports progress when the client supports it. Limits: 2–5 participants, 1–5 rounds; the shared `max_output_tokens` budget must allow at least 64 tokens per worst-case model call. Subagent spawning and resumable background execution are not implemented yet.

`run_solo.max_output_tokens` limits the requested generated output. Provider-reported completion-token usage is logged. `run_discussion.max_output_tokens` is a shared completion-token budget reserved across concurrent calls; providers that omit usage are charged the full reservation. This is not a dollar-cost limit and excludes prompt/input tokens.

## Provider support

The client uses `/chat/completions` on an OpenAI-compatible API. Configure the provider endpoint with `API_AGENT_BASE_URL`; the API key is read from `API_AGENT_API_KEY`. Secrets are not stored in profile records.

## Development

```bash
uv sync --extra test
uv run pytest
```

## Roadmap

1. Solo mode and profile registry
2. Bounded Discussion with independent proposals, critics, judge, blackboard, and output-token budget (current)
3. Subagent verification and resumable background execution for long-running discussions