HTTP / REST / A2A agents

1. Add traces

Install the SDK and call init() once at startup. Wrap each user↔agent exchange in a turn():

import eldros_sdk

eldros_sdk.init(traffic_type="prod")

@app.post("/chat")
async def chat(request: Request):
    body = await request.json()
    user_msg = body["message"]

    with eldros_sdk.turn(user_msg, session_id=body.get("session_id")) as t:
        reply = await agent.respond(user_msg)   # LLM call nests under the turn automatically
        t.reply(reply)                          # records the assistant turn

    return {"reply": reply}

turn() opens a span and makes it the active span — any auto-instrumented LLM or tool call inside nests underneath it automatically. t.reply() records the assistant response as the transcript.

2. Connect simulation

When Eldros runs a test scenario it sends W3C traceparent + baggage headers on every request. Continue them with one line around your handler:

@app.post("/chat")
async def chat(request: Request):
    body = await request.json()
    user_msg = body["message"]

    with eldros_sdk.trace_context(dict(request.headers)):   # ← add this
        with eldros_sdk.turn(user_msg, session_id=body.get("session_id")) as t:
            reply = await agent.respond(user_msg)
            t.reply(reply)

    return {"reply": reply}

trace_context works with FastAPI, Flask, Starlette, A2A, JSON-RPC — any HTTP framework. On production requests (no Eldros headers) it is a no-op, so you keep one handler for both. When the headers are present, every span is stamped with:

episode.id — links the trace to the specific test run
traffic_type="simulation" — keeps test traffic out of your production views

For simulation, t.reply() is optional — Eldros already has the transcript from the platform side. turn() is still required so each LLM/tool span is linked to the correct turn, giving you a structured trace even without the client-side transcript.

3. Integration modes

Pick the mode that matches what you need: Simulation + production observability (recommended)
Full transcript and traces for both production and eval runs:

eldros_sdk.init(traffic_type="prod")
# handler: trace_context + turn() + t.reply()

Simulation only
Only export during Eldros-driven test runs. Production traffic goes through normally but nothing is sent to the backend. t.reply() optional — platform has the transcript:

eldros_sdk.init(traffic_type="prod", simulation_only=True)
# handler: trace_context + turn() — t.reply() optional

Production observability only
No simulation integration. Full transcript required since there is no platform-side record:

eldros_sdk.init(traffic_type="prod")
# handler: turn() + t.reply() — no trace_context needed

Traces without turn() — in any mode — cannot be correlated to specific conversation turns. The transcript is what gets judged; traces explain the verdict.

A2A agents

A2A is JSON-RPC over HTTP — the same pattern applies. Use the official a2a-sdk and place trace_context inside your AgentExecutor.execute():

from a2a.server.agent_execution import AgentExecutor, RequestContext
from a2a.server.events import EventQueue

class MyAgentExecutor(AgentExecutor):
    async def execute(self, context: RequestContext, event_queue: EventQueue) -> None:
        user_msg = context.get_user_input()

        with eldros_sdk.trace_context(context.request.headers):   # A2A request headers
            with eldros_sdk.turn(user_msg) as t:
                reply = await agent.respond(user_msg)
                t.reply(reply)

        # enqueue A2A response events as normal

Everything else — init(), simulation_only, the three integration modes — is identical to the HTTP section above.

Getting started

Integrations

Concepts

HTTP / REST / A2A agents

1. Add traces

2. Connect simulation

3. Integration modes

A2A agents

​1. Add traces

​2. Connect simulation

​3. Integration modes

​A2A agents

1. Add traces

2. Connect simulation

3. Integration modes

A2A agents