Instructions & Actions

Overview

Agent instructions and actions form the core of agent behavior in Compozy. Instructions define the agent's personality and general behavior, while actions provide structured interfaces for specific tasks with validated inputs and outputs.

Instructions and actions heavily use YAML Templates for dynamic behavior. Understanding Context Variables and Sprig Functions is essential for creating responsive agents.

Agent Instructions

Instructions are the system prompts that define how an agent should behave, think, and respond. They establish the agent's identity, capabilities, and constraints.

Writing Effective Instructions

instructions: |
  You are a [role/identity].

  Your primary responsibilities:
  - [Responsibility 1]
  - [Responsibility 2]
  - [Responsibility 3]

  Guidelines:
  - [Behavioral guideline 1]
  - [Behavioral guideline 2]

  Constraints:
  - [Limitation 1]
  - [Limitation 2]

Instruction Best Practices

Actions

Actions are structured tasks that agents can perform with defined inputs, outputs, and specific prompts. They provide type-safe interfaces for agent capabilities.

Action Structure

Actions provide structured interfaces for specific agent capabilities. Each action defines what the agent should do, what inputs it expects, and what outputs it will produce. This structure enables type-safe interactions and predictable behavior.

actions:
  - id: action_identifier
    prompt: "Specific instructions for this action"
    input:
      type: object
      properties:
        param1:
          type: string
          description: "Parameter description"
      required: ["param1"]
    output:
      type: object
      properties:
        result:
          type: string
          description: "Result description"
    json_mode: true
    with:
      default_param: "default_value"

Action Components

Component	Description
ID	Unique identifier used to invoke the action from workflow tasks
Prompt	Specific instructions for this action, can include template variables
Input Schema	JSON Schema defining expected input parameters and validation rules
Output Schema	JSON Schema defining the structure of the action's response
JSON Mode	Forces structured JSON output when enabled
Default Parameters	Pre-configured values merged with runtime inputs

Action Examples

actions:
  - id: review-code
    prompt: |
      Analyze the provided {{.input.language}} code for:
      1. Code quality and readability
      2. Potential bugs or errors
      3. Performance optimizations
      4. Security vulnerabilities
      5. Best practice violations

      Provide specific, actionable feedback with examples.
    input:
      type: object
      properties:
        code:
          type: string
          description: "Source code to review"
        language:
          type: string
          enum: ["python", "javascript", "go", "java"]
          description: "Programming language"
        focus_areas:
          type: array
          items:
            type: string
            enum: ["security", "performance", "style", "bugs"]
          description: "Specific areas to focus on"
      required: ["code", "language"]
    output:
      type: object
      properties:
        summary:
          type: string
          description: "Overall assessment"
        issues:
          type: array
          items:
            type: object
            properties:
              severity:
                type: string
                enum: ["critical", "high", "medium", "low"]
              category:
                type: string
              line_number:
                type: integer
              description:
                type: string
              suggestion:
                type: string
        score:
          type: number
          minimum: 0
          maximum: 10
    json_mode: true

Template Variables in Actions

Actions support template variables that allow dynamic content based on workflow context:

prompt: |
  Analyze the activity "{{.item}}" in {{.workflow.input.city}}
  Weather conditions: {{.tasks.weather.output | toJson}}
  User preferences: {{.memory.user_preferences}}
  Current iteration: {{.index}}

Variable	Description
`{{.input.*}}`	Action input parameters passed at runtime
`{{.workflow.input.*}}`	Workflow input data available throughout execution
`{{.tasks.*.output}}`	Previous task outputs for chaining results
`{{.item}}`	Current item in collection tasks iteration
`{{.index}}`	Current index in collection tasks iteration
`{{.memory.*}}`	Memory values for stateful workflows
`{{.env.*}}`	Environment variables for configuration

Dynamic Action Selection

Actions can be selected dynamically based on workflow state using router tasks:

tasks:
  - id: process-request
    type: router
    condition: '{{.workflow.input.request_type}}'
    routes:
      analysis:
        type: basic
        $use: agent(local::agents.#(id="analyst"))
        action: analyze-data
      generation:
        type: basic
        $use: agent(local::agents.#(id="writer"))
        action: generate-content

Advanced Patterns

Multi-Step Actions

Create complex workflows by chaining actions:

actions:
  - id: research
    prompt: "Research the topic and gather key information"
    output:
      type: object
      properties:
        findings:
          type: array
          items:
            type: string

  - id: outline
    prompt: |
      Based on research findings: {{.tasks.research.output.findings | toJson}}
      Create a detailed outline for the article
    output:
      type: object
      properties:
        sections:
          type: array

  - id: write
    prompt: |
      Using the outline: {{.tasks.outline.output | toJson}}
      Write the complete article

Conditional Instructions

Adapt agent behavior based on context:

instructions: |
  You are a customer service agent.

  {{if eq .workflow.input.priority "high"}}
  IMPORTANT: This is a high-priority customer. Provide expedited service
  and escalate any issues immediately.
  {{end}}

  {{if .workflow.input.customer_tier}}
  Customer tier: {{.workflow.input.customer_tier}}
  Apply appropriate service level protocols.
  {{end}}

Best Practices

Instruction Clarity

Write instructions that are clear, specific, and leave no room for ambiguity. Define the agent's role precisely and set explicit boundaries.

Action Focus

Each action should have a single, well-defined purpose. Avoid combining multiple operations in one action for better modularity.

Schema Validation

Always define input/output schemas for predictable behavior. Use JSON Schema to ensure type safety and validation.

Error Handling

Include error scenarios in prompts and output schemas. Design actions to gracefully handle edge cases and invalid inputs.

Next Steps

Tools

Learn how agents use tools to extend their capabilities

Structured Outputs

Master JSON mode and output validation

Instructions & Actions

Be Specific and Clear

Set Boundaries

Provide Context

Optimize for Task

Instruction Clarity

Action Focus

Schema Validation

Error Handling

On this page