Skip to main content

​
Basic Usage

from typing import Annotated
from agentstack_sdk.a2a.extensions import TrajectoryExtensionServer, TrajectoryExtensionSpec

@server.agent()
async def my_agent(
    input: Message,
    context: RunContext,
    trajectory: Annotated[TrajectoryExtensionServer, TrajectoryExtensionSpec()]
):
    yield trajectory.trajectory_metadata(
        title="Planning",
        content="Analyzing the user request to determine the best approach..."
    )

    # Do work

    yield trajectory.trajectory_metadata(
        title="Execution",
        content="Processing data with temperature=0.7"
    )

    yield "Final result"

​
Markdown Support

The content field of trajectory_metadata supports Markdown, which is rendered directly in the UI. Supported elements include:
  • Headers
  • Bold and italic text
  • Ordered and unordered lists
  • Tables
  • Code blocks
  • Links
yield trajectory.trajectory_metadata(
    title="Checklist",
    content="""
- Load data
- Validate schema
- Run inference
- Generate report
"""
)

​
Grouping Trajectories

Use the group_id parameter to update trajectory content in the UI. Each update replaces the previous content (and title, if defined) for the same group_id: 
# Initial search status
yield trajectory.trajectory_metadata(
    title="Web search",
    content="Querying search engines...",
    group_id="websearch"
)

# Update with results
yield trajectory.trajectory_metadata(
    content="Found 8 results",
    group_id="websearch"
)
yield trajectory.trajectory_metadata(
    content="Found 8 results\nAnalyzed 3/8 results",
    group_id="websearch"
)
yield trajectory.trajectory_metadata(
    content="Found 8 results\nAnalyzed 8/8 results",
    group_id="websearch"
)

# Final update
yield trajectory.trajectory_metadata(
    title="Web search finished",
    content="Found 8 results\nAnalyzed 3/8 results\nExtracted key information",
    group_id="websearch"
)

​
Common Patterns

Progress Steps: 
yield trajectory.trajectory_metadata(title="Step 1", content="Loading data...")
yield trajectory.trajectory_metadata(title="Step 2", content="Processing...")
yield trajectory.trajectory_metadata(title="Step 3", content="Generating output...")
Decision Points: 
yield trajectory.trajectory_metadata(
    title="Tool Selection",
    content="Choosing search tool based on query type: factual"
)
Error Handling: 
yield trajectory.trajectory_metadata(
    title="Retry Attempt",
    content="First attempt failed, trying alternative approach..."
)
Multi-step Process with Live Updates: 
# Use group_id to show progress updates in a single section
yield trajectory.trajectory_metadata(
    title="Data Processing",
    content="Starting...",
    group_id="processing"
)
yield trajectory.trajectory_metadata(
    content="Processing batch 1/10...",
    group_id="processing"
)
yield trajectory.trajectory_metadata(
    content="Processing batch 10/10...",
    group_id="processing"
)
yield trajectory.trajectory_metadata(
    content="Processing complete! Processed 10 items",
    group_id="processing"
)
Trajectory steps appear as expandable sections in the UI, helping users understand your agent’s thought process.