Agent Context

Overview

Context in Compozy agents refers to all the information available to an agent during execution - from workflow inputs and previous task outputs to memory and environment variables. Effective context management is crucial for agent performance and accuracy.

Context Sources

Agents have access to multiple context sources:

Loading diagram...

Context Variables

Workflow Context

Workflow context provides agents with access to the initial workflow parameters, execution metadata, and configuration. This enables agents to understand the broader context of their task and make decisions based on workflow-level information.

Access workflow-level information:

actions:
  - id: process-request
    prompt: |
      Process request for: {{.workflow.input.user_name}}
      Request ID: {{.workflow.input.request_id}}
      Priority: {{.workflow.input.priority}}

      Workflow metadata:
      - Started at: {{.workflow.started_at}}
      - Workflow ID: {{.workflow.id}}

Property	Template Variable	Description
Workflow Input	`{{.workflow.input.*}}`	All workflow input parameters passed at execution time
Workflow Metadata	`{{.workflow.id}}`	Unique workflow execution ID for tracking
Timing Information	`{{.workflow.started_at}}`	Workflow start timestamp for duration calculations
Configuration	`{{.workflow.config.*}}`	Workflow configuration values from YAML definition

Task Context

Task context allows agents to access the results of previous tasks in the workflow. This enables building complex workflows where agents can analyze, combine, and build upon the work of previous tasks.

Access outputs from previous tasks:

actions:
  - id: analyze-results
    prompt: |
      Analyze the combined results:

      Weather data: {{.tasks.weather.output | toJson}}
      Temperature: {{.tasks.weather.output.temperature}}°C

      User preferences: {{.tasks.preferences.output.items}}

      Previous analysis:
      {{range .tasks.initial_analysis.output.findings}}
      - {{.}}
      {{end}}

Property	Template Variable	Description
Complete Output	`{{.tasks.TASK_ID.output}}`	Access the complete output object from a task
Specific Fields	`{{.tasks.TASK_ID.output.field}}`	Access specific fields within task output
Task Status	`{{.tasks.TASK_ID.status}}`	Check task execution status (completed, failed, etc.)
Error Handling	`{{.tasks.TASK_ID.error}}`	Access task error information if execution failed

Collection Context

Collection context is available when agents execute within collection tasks. This provides access to the current item being processed, its index, and information about the collection itself.

In collection tasks, access current item and index:

tasks:
  - id: process-items
    type: collection
    items: "{{.workflow.input.items}}"
    task:
      type: basic
      $use: agent(local::agents.#(id="processor"))
      action: process-item

agents:
  - id: processor
    actions:
      - id: process-item
        prompt: |
          Process item {{.index}} of {{len .parent.items}}:
          Current item: {{.item | toJson}}

          Previous items processed: {{.index}}
          Items remaining: {{sub (len .parent.items) .index}}

Memory Context

Memory context provides agents with access to persistent conversation history and user context. When agents have memory references configured, the memory content is automatically included in their context during execution.

Access memory content in prompts:

agents:
  - id: contextual-agent
    memory:
      - id: user_context
        key: "user:{{.workflow.input.user_id}}"

    actions:
      - id: personalized-response
        prompt: |
          Respond to: {{.input.message}}

          The conversation history and user preferences are
          automatically included from memory.

          Build on previous context naturally.

Context Building Strategies

Context building strategies help you organize and optimize how information is provided to agents. Choose the right strategy based on your workflow requirements and token budget.

Hierarchical Context

Hierarchical context organization helps agents understand information at different levels of scope. By structuring context from global to specific levels, agents can better understand the environment and make appropriate decisions.

instructions: |
  You are a {{.workflow.input.agent_role}} assistant.

  Global context:
  - Organization: {{.env.ORG_NAME}}
  - Environment: {{.env.ENVIRONMENT}}

  User context:
  - User ID: {{.workflow.input.user_id}}
  - User tier: {{.workflow.input.user_tier}}

  Session context:
  - Session ID: {{.workflow.input.session_id}}
  - Session start: {{.workflow.input.session_start}}

Selective Context

Selective context inclusion helps optimize token usage by only including relevant information for the specific task. This approach reduces costs and improves agent focus by removing irrelevant data.

Include only relevant context to optimize token usage:

actions:
  - id: focused-analysis
    prompt: |
      Analyze the sales data for Q4.

      {{/* Only include relevant context */}}
      Q4 Revenue: {{.tasks.revenue_calc.output.q4_total}}
      YoY Growth: {{.tasks.revenue_calc.output.growth_rate}}%

      {{/* Omit irrelevant quarterly data to save tokens */}}

Dynamic Context

Dynamic context building allows agents to adapt their context based on runtime conditions. This enables flexible agent behavior that changes based on user preferences, workflow parameters, or task requirements.

Build context based on conditions:

actions:
  - id: adaptive-response
    prompt: |
      {{if .workflow.input.include_history}}
      Historical context:
      {{range .tasks.fetch_history.output.events}}
      - {{.date}}: {{.description}}
      {{end}}
      {{end}}

      {{if eq .workflow.input.mode "detailed"}}
      Provide a comprehensive analysis including:
      - Root cause analysis
      - Impact assessment
      - Mitigation strategies
      {{else}}
      Provide a brief summary of key findings.
      {{end}}

Context Templates

Template Functions

Compozy supports Sprig template functions:

prompt: |
  # String manipulation
  Title: {{.input.title | upper}}
  Slug: {{.input.title | lower | replace " " "-"}}

  # Date formatting
  Current date: {{now | date "2006-01-02"}}
  Deadline: {{.input.deadline | date "Jan 2, 2006"}}

  # Conditionals
  Priority: {{.input.priority | default "normal"}}
  Status: {{if .tasks.validation.output.passed}}approved{{else}}rejected{{end}}

  # Lists and iteration
  Total items: {{len .input.items}}
  {{range $i, $item := .input.items}}
  {{$i}}: {{$item.name}} ({{$item.status}})
  {{end}}

  # Math operations
  Average: {{div (add .output.score1 .output.score2) 2}}
  Percentage: {{mul (div .output.completed .output.total) 100}}%

JSON Handling

Work with JSON data in context:

prompt: |
  # Pretty print JSON
  Configuration:
  {{.tasks.config.output | toPrettyJson}}

  # Parse JSON string
  {{$data := .input.json_string | fromJson}}
  Parsed value: {{$data.field}}

  # Convert to JSON
  Items as JSON: {{.input.items | toJson}}

Next Steps

Structured Outputs

Learn about JSON mode and output validation

On this page