013: Agent/Scopes

The Scoped context pattern is a fundamental mechanism for managing the context available to a Call. In a complex agentic system, a Call rarely executes in a vacuum; it often needs access to information from its parent environment, such as user input, current state, or the results of previous steps. Scoped context provides a secure and explicit way to control this flow of information.

By restricting the context, scopes enhance security, prevent accidental data leakage, and focus the LLM, leading to more predictable and cost-effective executions. This controlled context is also the key to modularity, allowing components like Ideas and Activities to be truly self-contained and reusable. This document explains how this pattern works and how it composes with other agent capabilities.

Provisioning vs. Requesting Context

The schema for the _scopes property determines whether context is statically provisioned or dynamically requested at runtime.

• Static Scopes (Context Provisioning): The _scopes schema can be a const value, which means the context is provisioned. The designer has hard-coded the exact context the tool is allowed to see.

  {
    "_scopes": {
      "const": ["input"]
    }
  }
  

• Dynamic Scopes (Context Requesting): The _scopes schema can be more flexible, allowing the context to be requested. The LLM decides which of the available scopes it needs to generate the Call.

  {
    "_scopes": {
      "type": "array",
      "items": {
        "enum": ["state", "input"]
      }
    }
  }
  

  This dynamic pattern is especially powerful when combined with a human-in-the-loop approval system, providing a critical layer of transparency and control.

The Role of Scopes in Call Composition

The _scopes property is the primary mechanism for controlling the context available to a Call. It acts as an allow-list, filtering the parent environment to provide a focused, limited field of view for the execution. This controlled context is fundamental to how a Call is processed, and its role adapts to support a compositional model of execution where different capabilities like explicit logic, instancing, and modularity can be combined.

• • 002: Agent/Tool.

  Latent Execution: In the default latent execution, _scopes serve as a "nudge" to focus the LLM's attention on relevant parts of the parent context. This is a best-effort guide, not a strict filter, but it is crucial for improving the reliability and cost-effectiveness of LLM-driven reasoning by reducing noise from irrelevant data. See the Disambiguation with Scopes example.

• • 003: Agent/Activity.

  Explicit Execution (_activity): When a Call is backed by a deterministic Activity, the role of scopes becomes more direct. The scoped context is passed wholesale to the Activity function as an additional parameter. This gives the Activity full access to the necessary contextual data, even if that data wasn't directly used by the LLM to generate the Call's primary parameters. See the Providing Context to an Activity example.

• • 011: Agent/Instancing

  Instancing (_instance): In a multi-instance request where the agent processes a batch of similar data objects, scopes become instance-aware. The protocol ensures that a Call targeting a specific instance receives only the context for that instance. This is critical for maintaining data integrity and preventing context from "leaking" between parallel executions.

• • 012: Agent/Delegate

  Delegated Isolation (_delegate): When a Call is delegated to an external Delegate, scopes act as the gatekeepers of context. They define what from the parent's environment gets appended to the delegate's own internal context, creating the final context for the isolated sub-request. Nothing from the parent is available unless explicitly scoped, ensuring true encapsulation. See the Scoping a Delegate's Context and Instancing with Scoped Delegates examples.

The _scopes property is the bridge that allows a Call to receive context. This chapter has shown how this single mechanism adapts to different execution modes—from gently guiding a latent call to strictly defining the entire context for a delegated one. This flexibility is what makes it a cornerstone of building complex, secure, and modular agentic systems.

Examples

[
  {
    "type": "state",
    "currentUser": { "id": "user_A", "name": "Alice" }
  },
  {
    "type": "input",
    "mentionedUser": { "id": "user_B", "name": "Bob" },
    "instruction": "Send a welcome message to the user mentioned above."
  }
]

{
  "_tool": "sendMessage",
  "_scopes": ["input"],
  "recipientId": "user_B",
  "message": "Welcome, Bob!"
}

{
  "_tool": "logEvent",
  "_scopes": ["state"],
  "eventName": "user_login"
}

// The parameters are destructured to directly access 'eventName'
// from the call and 'state' from the scoped context.
Activity.register('logEvent', async ({ eventName }, { state }) => {
  const userId = state.userId;
  await analytics.track(eventName, { userId });
});

// Orchestrator's Context and Call
[
  {
    "type": "state",
    "articleText": "A long and complex article..."
  },
  {
    "_tool": "summarizeArticle",
    "_delegate": "SummarizerAgent",
    "_scopes": ["state"]
  }
]

// Context constructed for the Summarizer's sub-request
[
  // The Summarizer's internal context
  {
    "type": "system",
    "message": "You are an expert summarizer."
  },
  // The scoped context from the parent is appended
  {
    "type": "state",
    "articleText": "A long and complex article..."
  }
]

// PARENT CONTEXT
[
  { "type": "state", "_instance": "①", "text": "Hello" },
  { "type": "state", "_instance": "②", "text": "Bonjour" }
]

// LLM'S SOLUTION
{
  "calls": [
    {
      "_tool": "translate",
      "_delegate": "translatorDelegate",
      "_instance": "①",
      "_scopes": ["state"]
    },
    {
      "_tool": "translate",
      "_delegate": "translatorDelegate",
      "_instance": "②",
      "_scopes": ["state"]
    }
  ]
}

// CONTEXT FOR DELEGATE ①
[
  { "type": "system", "message": "You are a translator." },
  { "type": "state", "text": "Hello" }
]

// CONTEXT FOR DELEGATE ②
[
  { "type": "system", "message": "You are a translator." },
  { "type": "state", "text": "Bonjour" }
]