Context System

The context system is how you keep your agent’s responses grounded in your own data — injecting runtime state, instructions, and per-agent knowledge into each request without fine-tuning.

Knowledge (moved to per-agent local folders)

The cloud knowledge upload feature (file upload, /api/knowledge-index, chunked vectors, the knowledgeMode/contextFileContents/knowledgeSnippets/shallowKnowledgeEntries payload fields) was removed in the 2026-04-21 cloud-knowledge-removal work. Knowledge is now provided via per-agent local folders (agents/<name>/knowledge/) checked into the agent repo and searched from Python via the search_knowledge tool. Each agent chooses what knowledge to expose and how to query it at runtime.

Prompt Pipeline

The prompt pipeline is the internal process that composes the final system prompt sent to the AI engine. When usePromptPipeline is true, the pipeline assembles context from the agent profile and request:

  1. Main task — The agent’s mainTask from its profile configuration.
  2. Agent persona — The personality description from agentPersona.
  3. Available commands — The command list from availableCommands.
  4. Command states — Current state information from the local runtime.
  5. Custom instructions — Any additional instructions from the configuration.
  6. System instruction suffix — A final override appended at the end.

Command States

In ToolRunner workflows, the agent needs to know the current state of the system it is controlling. Command states provide this context: 

response = client.chat(
    "What should I do next?",
    agent_name="warehouse-bot",
    commandStates={
        "current_zone": "A3",
        "items_picked": 4,
        "items_remaining": 2,
        "battery_level": 72,
        "obstacles_detected": False,
    },
)

The command states are serialized and injected into the system prompt so the AI engine can make informed decisions based on the current reality of the system.

The systemInstructionRequest Object

Under the hood, the prompt pipeline builds a systemInstructionRequest object that contains all the context fields. Understanding this object helps when you need fine-grained control over the prompt composition:

Field Type Description
mainTask string Primary system instruction from the agent profile.
agentPersona string Personality and tone description.
availableCommands string Comma-separated list of valid commands.
availableActions string Available action categories.
commandStates object Current state of the controlled system.
systemInstructionSuffix string Text appended to the very end of the composed prompt.
usePromptPipeline boolean Whether to enable automatic prompt composition.
userName string Display name for the user in conversation.

System Instruction Suffix

The systemInstructionSuffix field lets you append text to the end of the composed system prompt. This is the last thing the AI engine reads before generating a response, giving it high influence over output format and behavior. 

response = client.chat(
    "List the top 3 products",
    agent_name="catalog-agent",
    systemInstructionSuffix="Always respond in JSON format with keys: "
                           "products (array of {name, price, rating}).",
)

Use this for request-specific formatting overrides, safety constraints, or output structure requirements that differ from the default profile configuration.

Best Practices

  • Use the suffix for formatting. Rather than embedding format instructions in the main task, use systemInstructionSuffix for request-specific output requirements.
  • Minimize redundant context. Including too much context dilutes the signal. Only inject information that is relevant to the current request.
  • Leverage command states for live data. For information that changes every second (sensor readings, system status), use command states rather than stuffing it into the main task.

Next Steps