> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dagraph.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Install dagraph: pip, uv, and backend configuration

> Requirements, pip and uv install options, source install, and step-by-step setup for all 7 LLM backends including claude_code, OpenAI, Gemini, and Bedrock.

dagraph is a Python CLI tool distributed on PyPI as the `dagraph` package. This page covers system requirements, install options, and how to configure each of the 7 supported LLM backends.

## Requirements

* **Python 3.12 or newer** — dagraph uses features not available in earlier versions.
* **[uv](https://docs.astral.sh/uv/getting-started/installation/)** — recommended for managing Python environments and fast installs.
* **`claude` CLI** — required only for the default `claude_code` backend. Install it from [claude.ai/code](https://claude.ai/code) and ensure it is on your PATH.

## Install

<Tabs>
  <Tab title="pip">
    ```bash theme={null}
    pip install dagraph
    ```
  </Tab>

  <Tab title="uv">
    ```bash theme={null}
    uv pip install dagraph
    ```
  </Tab>

  <Tab title="From source">
    Clone the repository and install in editable mode with development dependencies:

    ```bash theme={null}
    git clone https://github.com/tamboo-dev/agentgraph.git
    cd agentgraph
    uv venv --python 3.12
    uv pip install -e ".[dev]"
    ```

    The `[dev]` extra includes `pytest`, `ruff`, and `mypy`.
  </Tab>
</Tabs>

## Verify the install

```bash theme={null}
agentgraph --version
```

You can also validate one of the bundled examples to confirm the engine is working:

```bash theme={null}
agentgraph validate examples/research.yaml
# ✓ research: 4 nodes, 2 wave(s)
#   wave 1: ['research_a', 'research_b', 'research_c']
#   wave 2: ['synthesizer']
```

## Backend setup

dagraph supports 7 executor backends. The default is `claude_code`. You can override the default at run time with `--backend <name>`, or route individual nodes to a specific backend using a model-prefix in the `model` field (e.g. `openai/gpt-4o`).

### `claude_code` (default)

Spawns `claude -p` as a subprocess and bills against your Claude Code subscription. No API key required.

**Setup:** Install the `claude` CLI and confirm it is on your PATH:

```bash theme={null}
claude --version
```

### `api` (Anthropic Messages API)

Calls the Anthropic API directly. Billed per token.

**Setup:** Set `ANTHROPIC_API_KEY` in your environment or in a `.env` file at the project root:

```bash theme={null}
ANTHROPIC_API_KEY=sk-ant-...
```

### `openai`

Calls the OpenAI Chat Completions API. Billed per token.

**Setup:**

```bash theme={null}
OPENAI_API_KEY=sk-...
```

### `gemini`

Calls the Google GenAI API. Billed per token.

**Setup:**

```bash theme={null}
GEMINI_API_KEY=AIza...
```

### `bedrock`

Calls Anthropic models via AWS Bedrock. Billed per token through your AWS account.

**Setup:** Install the `[bedrock]` extra, then configure your AWS credentials using any method in the [AWS credential chain](https://docs.aws.amazon.com/sdkref/latest/guide/standardized-credentials.html) (environment variables, `~/.aws/credentials`, IAM role, etc.):

```bash theme={null}
pip install "dagraph[bedrock]"
```

```bash theme={null}
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...
AWS_DEFAULT_REGION=us-east-1
```

### `ollama`

Runs models locally via an [Ollama](https://ollama.com) daemon. Free to use.

**Setup:** Start the Ollama daemon so it is listening on `localhost:11434`:

```bash theme={null}
ollama serve
```

Then pull a model before running a workflow that uses it:

```bash theme={null}
ollama pull llama3.2
```

### `codex`

Runs OpenAI Codex via the `codex` CLI. Billed against your OpenAI Codex plan.

**Setup:** Install the `codex` CLI and confirm it is on your PATH:

```bash theme={null}
codex --version
```

## .env file setup

For API-key backends, create a `.env` file in your project directory. dagraph loads it automatically at startup:

```bash theme={null}
# .env
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GEMINI_API_KEY=AIza...
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...
AWS_DEFAULT_REGION=us-east-1
```

<Warning>
  Never commit your `.env` file to version control. Add it to `.gitignore`.
</Warning>

## Model-prefix routing

You can mix backends within a single workflow by prefixing the `model` field. dagraph detects the prefix and routes to the matching executor regardless of the `--backend` flag:

```yaml theme={null}
nodes:
  - id: brainstorm
    type: agent
    model: anthropic/claude-sonnet-4-6   # → api backend
    prompt: "..."

  - id: check
    type: agent
    model: openai/gpt-4o                 # → openai backend
    prompt: "..."

  - id: summarize
    type: agent
    model: ollama/llama3.2               # → ollama backend (local)
    prompt: "..."
```

Nodes without a prefix use the backend set by `--backend` (default: `claude_code`).

## Fallback chains

To keep a workflow running when a provider has an outage, declare a `fallback_chain` on any agent node. dagraph tries each model in order and uses the first successful response:

```yaml theme={null}
- id: research_a
  type: agent
  model: claude-sonnet-4-6
  fallback_chain:
    - openai/gpt-4o
    - ollama/llama3.2
  prompt: "..."
```

<Tip>
  Auth errors (HTTP 401/403) and bad-request errors (400/422) skip the fallback chain — a different provider will not fix invalid credentials or malformed requests.
</Tip>