013: Agent/Scopes

The Scoped context idea is a core rule for managing what an AI can see when it performs a task, or Call. In a big AI system, a task doesn't just happen on its own; it needs information from its surroundings, like what a user asked for, what happened in previous steps, or the current situation. Scopes provide a safe and clear way to control what information gets passed along.

By limiting what the AI sees, scopes make the system safer, prevent it from accidentally sharing private data, and help the AI focus. This makes its actions more predictable and saves money. This controlled view is also a key reason why different parts of the system, like Ideas and Activities, can be built like self-contained and reusable tools. This document explains how scopes work and how they fit together with other AI abilities.

Giving vs. Asking For Information

Depending on how you set up the _scopes rule, the AI can either be given the information it needs automatically, or it can ask for it when it's running.

• Static Scopes (Giving Information): If the _scopes rule has a const (constant) value, it means the information is pre-approved and given. The programmer has decided ahead of time the exact information the tool is allowed to see.

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

• Dynamic Scopes (Asking For Information): The _scopes rule can also be flexible, which lets the AI ask for the information it needs. The AI looks at the situation and decides which of the allowed pieces of info it needs to do its job.

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

  This asking pattern is really useful when you have a person check the AI's work. The AI can ask, "Can I see this piece of information?" and a human can approve it, adding an important layer of safety and control.

How Scopes Help Different Tasks Work Together

The _scopes property is the main way to control what an AI Call can see. It's like a permission slip that filters out all the unneeded information, giving the task a very limited and focused view. This is essential for how different kinds of tasks work, from simple thinking to using pre-built tools.

• • 002: Agent/Tool.

  Latent Execution (AI Thinking): When the AI is just thinking and figuring things out, _scopes act like a friendly hint to focus its attention on the important stuff. It's a gentle guide, not a strict rule, but it's very helpful for making the AI's thinking more reliable and cheaper by cutting out distracting information. See the Focusing on the Right User example.

• • 003: Agent/Activity.

  Explicit Execution (Using a Tool): When a Call uses a pre-programmed tool, or Activity, the scope's job is much more direct. The information it points to is handed directly to the tool as a package of extra data. This gives the tool all the context it needs to work, even if that info wasn't directly part of the AI's main command. See the Giving a Tool Extra Information example.

• • 011: Agent/Instancing

  Instancing (Working on a Batch): Imagine you ask the AI to do the same task on a list of 10 items. Scopes make sure that when the AI is working on item #5, it only sees the information for item #5. This is super important to keep data separate and prevent information from one task from spilling over and confusing another. It's like giving each worker their own separate desk with only their assigned papers.

• • 012: Agent/Delegate

  Delegated Isolation (Asking another AI for Help): When one AI agent asks a specialized agent (a Delegate) to handle a task, scopes act like a gatekeeper. They decide what information from the first agent's world gets added to the specialist's world. Nothing gets through unless it's on the list, making sure the specialist agent works in its own secure bubble. See the Giving Information to a Specialist Agent and Handling Batches with Specialist Agents examples.

The _scopes property is the bridge that connects a task to the information it needs. We've seen how this one simple idea changes its role for different situations—from gently guiding the AI's thoughts to strictly defining the information for a specialist tool. This flexibility is what makes it a key part of building smart, safe, and well-organized AI 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 code is set up to grab 'eventName' from the main command
// and 'state' from the extra scoped information.
Activity.register('logEvent', async ({ eventName }, { state }) => {
  const userId = state.userId;
  await analytics.track(eventName, { userId });
});

// The Orchestrator's information and its call for help
[
  {
    "type": "state",
    "articleText": "A long and complex article..."
  },
  {
    "_tool": "summarizeArticle",
    "_delegate": "SummarizerAgent",
    "_scopes": ["state"]
  }
]

// The information the Summarizer sees for its task
[
  // The Summarizer's own built-in instructions
  {
    "type": "system",
    "message": "You are an expert summarizer."
  },
  // The scoped information from the main agent is added
  {
    "type": "state",
    "articleText": "A long and complex article..."
  }
]

// MAIN AGENT'S DATA
[
  { "type": "state", "_instance": "①", "text": "Hello" },
  { "type": "state", "_instance": "②", "text": "Bonjour" }
]

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

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

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