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

# Quick Start

> Run your first custom agent evaluation in a few lines

## Prerequisites

1. [Install the SDK](/sdk/evaluations/installation).
2. [Build a dataset](/sdk/evaluations/build-dataset), or use an existing dataset ID from the AgentX dashboard.
3. Export `AGENTX_API_KEY` in your environment.

## Run an evaluation

```python theme={null}
from agentx import AgentX

client = AgentX.from_env()

def my_agent(case):
    return f"Answer to: {case.query}"

run_context = (
    client.evaluations
    .run(
        dataset_id="existing-dataset-id",
        subject={"kind": "custom_agent", "displayName": "My Agent", "framework": "raw_python"},
    )
    .execute(my_agent)
    .finalize()
)

# average_rating/min_rating/max_rating/rated_count are already available here, no need to
# call .analyze() just to see how the run went.
print(f"Average rating: {run_context.average_rating:.2f}")

report = run_context.analyze()
print(f"Dashboard: {report.dashboard_url}")
```

`client.evaluations.run()` creates the run, `.execute()` calls `my_agent` once per test case, scores each response immediately, and submits the results. `.finalize()` closes the run: `run_context.average_rating` (and `.min_rating` / `.max_rating` / `.rated_count`) read straight from those scores, no LLM analysis pass required. `.analyze()` is a separate, optional step that adds the qualitative report (strengths, weaknesses, recommendations) and returns it as `report`.

## Link each result to its trace

Trace the agent call and return the span's id alongside the output - three things light up at
once: a **View trace** button on every result row, **trajectory-aware judging** (the judge sees
the tools the agent actually called, not just the answer), and
[expected-trajectory matching](/sdk/evaluations/build-dataset#expected-trajectories) for cases
that declare `expected_tools`:

```python theme={null}
def my_agent(case):
    # sync=True populates span.trace_id before the block exits; monitor=False keeps the run's
    # own judge as the only scorer (no double-judging at ingest).
    with client.tracer.trace(
        "my-agent", input={"query": case.query}, sync=True, monitor=False
    ) as span:
        answer = run_my_agent(case.query)
        span.output = answer
    return {"output": answer, "trace_id": span.trace_id}
```

The dashboard's **Create evaluation** button (Evaluate → Runs) generates this exact scaffold
with your real dataset and evaluator ids inlined, in Simple, OpenAI, LangChain, or Google ADK
flavors.

## Configuration

`AgentX` reads environment variables via `.from_env()`:

| Variable              | Description                                                                                                                                                                                                                   |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AGENTX_API_KEY`      | Workspace API key (required)                                                                                                                                                                                                  |
| `AGENTX_API_BASE_URL` | Optional override for the API base URL                                                                                                                                                                                        |
| `AGENTX_WORKSPACE_ID` | Explicit workspace ID. Set this if your API key's user belongs to more than one workspace, otherwise datasets, configs, and runs are created in whichever workspace the key defaults to, which may not be the one you intend. |

Or pass configuration directly:

```python theme={null}
client = AgentX(
    api_key="your-key",
    base_url="https://your-agentx-instance.com",
    workspace_id="your-workspace-id",
)
```

## Next steps

<CardGroup cols={2}>
  <Card title="Build Dataset" icon="table" href="/sdk/evaluations/build-dataset">
    Create test cases instead of using an existing dataset
  </Card>

  <Card title="EvaluationSubject Fields" icon="tag" href="/sdk/evaluations/evaluation-subject">
    Describe your agent so analysis can check instruction adherence
  </Card>

  <Card title="Examples" icon="code" href="/sdk/evaluations/examples/overview">
    Framework-specific integration patterns
  </Card>

  <Card title="Submit Pre-Defined Results" icon="upload" href="/sdk/evaluations/examples/precomputed-results">
    Score outputs you already generated, without re-running the agent
  </Card>

  <Card title="Evaluation Settings" icon="sliders" href="/sdk/evaluations/evaluation-settings">
    Build one grading config once, run it against any dataset
  </Card>

  <Card title="Link a Trace to a Result" icon="route" href="/sdk/tracing#linking-a-trace-to-an-evaluation-result">
    Get a full Execution Timeline per result, not just a score
  </Card>
</CardGroup>