agentsflow 0.0.6
Add your description here
Requires Python: >=3.12

AgentsFlow
==========

[![Docs](https://img.shields.io/badge/docs-latest-0a7ea4?logo=readthedocs&logoColor=white)](https://docs.agentsflow.dev)

Agentsflow is the production-grade control plane for coding agents. It provides a harness that controls workflow setup, routing, and guardrails so coding agents stay on rails. Full operator and contributor docs live at [docs.agentsflow.dev](https://docs.agentsflow.dev).

Quick start (MCP)
-----------------
The easiest way to run AgentsFlow is as an MCP server using `uvx` (part of [uv](https://github.com/astral-sh/uv)).

Prerequisites
-------------
- `uvx` (install [uv](https://github.com/astral-sh/uv#installation) to get the `uvx` runner)
- Temporal CLI/dev server (for the local Web UI at http://localhost:8233): https://docs.temporal.io/cli
- One coding agent CLI: **Claude Code**, **Codex CLI**, or **Gemini CLI** (pick whichever assistant you use)

### Option 1: Use with AI Assistant (Recommended)
Run the following commands to add AgentsFlow as an MCP server.

**Claude Code**
```bash
claude mcp add agentsflow --scope user --env OPENAI_API_KEY=sk-... --env PROCESS_CODING_AGENT_PROVIDER=claude -- uvx agentsflow
```

**Gemini CLI**
```bash
gemini mcp add agentsflow --scope user --env OPENAI_API_KEY=sk-... --env PROCESS_CODING_AGENT_PROVIDER=gemini -- uvx agentsflow
```

**Codex CLI**
```bash
codex mcp add agentsflow --env OPENAI_API_KEY=sk-... --env PROCESS_CODING_AGENT_PROVIDER=codex -- uvx agentsflow
```

**Cursor** (`.cursor/mcp.json` or via Settings > MCP)
```json
{
  "mcpServers": {
    "agentsflow": {
      "command": "uvx",
      "args": ["agentsflow"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "PROCESS_CODING_AGENT_PROVIDER": "codex"
      }
    }
  }
}
```

`PROCESS_CODING_AGENT_PROVIDER` lets you choose which coding agent (claude / codex / gemini) AgentsFlow will route coding actions to.

### Option 2: Standalone HTTP Server
To run the stack independently (e.g. for debugging or remote access):
```bash
uvx agentsflow --transport streamable-http
```

### Tracking Progress
Regardless of how you run it (Option 1 or 2), you can track workflow execution and status in the Temporal Web UI at http://localhost:8233.

### 3. Use it
Once connected, you can use natural language to interact with the process workflow. A few concrete prompts:
- "Call `start_agentsflow_process` on this repo with issue https://jira.example.com/browse/TEAM-123."
- "Kick off `start_agentsflow_process` with task text 'Fix 500 error when cookie is missing' for the current repo."
- "The workflow paused; send these answers via `provide_agentsflow_clarification` and then `await_agentsflow_result` with the workflow id in a list (it returns after the first workflow finishes or pauses)."
- "Check the latest status for workflow `process-1a2b3c` using `await_agentsflow_result([\"process-1a2b3c\"])` and call again for additional workflows if needed."

You can supply either an issue URL or a free-text task when calling `start_agentsflow_process`, but not both.

Architecture (high level)
-------------------------
```mermaid
flowchart LR
  Dev[CLI / MCP client] -->|start process workflow| Temporal[Temporal Server]
  Temporal --> Worker[AgentsFlow worker]
  Worker --> Activities[Git / Issue / ACP activities]
  Activities --> Repo[(Git worktree)]
  Activities --> Providers[Jira or GitHub issues]
  Activities --> ACP[Claude / Gemini / Codex ACP]
```

Supported issue providers
-------------------------
| Provider | Credentials | Notes |
| --- | --- | --- |
| Jira | `JIRA_EMAIL` + `JIRA_API_TOKEN` (optional `JIRA_HOST_ALLOWLIST`, `JIRA_TIMEOUT_SECONDS`) | Hosts matching `atlassian.net`/`jira` or allowlisted domains route here. |
| GitHub | `GITHUB_TOKEN` (optional `GITHUB_TIMEOUT_SECONDS`) | Uses the GitHub Issues API for `github.com/<org>/<repo>/issues/<id>` URLs. |

Docs
----
- New operators: Quickstart + deployment: https://docs.agentsflow.dev
- Process workflow: https://docs.agentsflow.dev/latest/workflows/process/
- Providers + env reference: https://docs.agentsflow.dev/latest/guides/providers/