Agent Context

Agent context is passive identity metadata for agentic requests. It lets a harness label each LLM call with a top-level agent run and a specific reasoning/tool trajectory. Dynamo records this metadata in agent traces, but it does not change routing, scheduling, or cache behavior.

Request Schema

Each harness LLM call should include nvext.agent_context:

1
{
2
    "model": "my-model",
3
    "messages": [
4
        { "role": "user", "content": "Research Dynamo agent tracing." }
5
    ],
6
    "nvext": {
7
        "agent_context": {
8
            "session_type_id": "deep_research",
9
            "session_id": "research-run-42",
10
            "trajectory_id": "research-run-42:researcher",
11
            "parent_trajectory_id": "research-run-42:planner"
12
        }
13
    }
14
}

A single session_id can contain multiple parent and child trajectories. The field names align with the Agent Trajectory Interchange Format so harness trajectory files and Dynamo serving traces join without renaming; see the collapsed section at the bottom of this page for details.

OpenAI Client Integration

When using the OpenAI Python client, pass Dynamo’s extension fields through extra_body and set x-request-id through extra_headers:

1
import uuid
2
3
4
def instrument_llm_request(kwargs, agent_context):
5
    body = dict(kwargs.get("extra_body") or {})
6
    nvext = dict(body.get("nvext") or {})
7
    nvext["agent_context"] = dict(agent_context)
8
    body["nvext"] = nvext
9
10
    headers = dict(kwargs.get("extra_headers") or {})
11
    headers.setdefault("x-request-id", str(uuid.uuid4()))
12
13
    out = dict(kwargs)
14
    out["extra_body"] = body
15
    out["extra_headers"] = headers
16
    return out

x-request-id is the harness’s logical LLM-call ID. Dynamo copies it into request.x_request_id; it is separate from Dynamo’s internal request ID.

Harness Integration Pattern

An existing harness does not need to import Dynamo packages or link against Dynamo runtime APIs. Framework integrations should use this shape:

• Add a small helper module that stores the current agent_context in a context variable.
• Wrap each agent run with that context so LLM calls and tool records share the same session_id and trajectory_id.
• Call one helper before each OpenAI-compatible LLM request to merge extra_body.nvext.agent_context and set x-request-id.
• Propagate context through thread pools, subprocesses, and subagent launches when those paths can make LLM calls or emit tool records.
• Include parent_trajectory_id when launching a subagent from a known parent trajectory.

For trace sink setup, tool event relay, and record schema details, see Agent Tracing.