/docs / agents / tools & delegation

Tools & Delegation

Agents can scope which tools are available in different contexts, expose sidecar HTTP endpoints as native LLM tools, and delegate tasks to other installed agents. This page covers tool scoping, sidecar tool definitions, and multi-agent delegation.

Tool Scoping

Agents can declare named scopes that restrict which tools, skills, and plugins are available in a given context. This lets the same agent operate with different capabilities depending on where it runs.

Declaration in agent.json

Scopes are defined in the scopes field of agent.json:

{
  "scopes": {
    "write": { "tools": ["file_write", "email_send"], "skills": [], "plugins": [] },
    "read": { "tools": ["file_read", "email_search"], "skills": [], "plugins": [] }
  }
}

Each scope is a ToolScope struct with three fields:

Field	Type	Description
`tools`	string[]	Tool names to allow
`skills`	string[]	Skill qualified names to allow
`plugins`	string[]	Plugin install codes to allow

Usage

SDK embeds pass a scope parameter, and the runner restricts tool access to that named scope's allowlist:

nebo.chat.mount(container, { scope: "read" });

Use case: A public-facing embed uses the read scope (search and view only), while the main Nebo UI uses the write scope (full access). Same agent, different capabilities per context.

Sidecar Tool Definitions

Tools can be declared directly in agent.json, turning sidecar HTTP endpoints into native LLM tools (not proxied through a wrapper):

{
  "tools": [
    {
      "name": "get_document",
      "description": "Fetch a document by ID",
      "method": "GET",
      "path": "/documents/{id}",
      "input_schema": {
        "type": "object",
        "properties": {
          "id": { "type": "string" }
        }
      }
    }
  ]
}

Behavior

Each entry becomes a tool the LLM can call directly
Path parameters are resolved from input: /documents/{id} with {"id": "abc"} becomes /documents/abc
HTTP method determines body vs query handling (GET uses query params, POST/PUT/PATCH send a JSON body)
Discovery is also available via a GET /_tools endpoint on the sidecar, returning the same format

Multi-Agent Delegation

An agent can delegate tasks to other installed agents using the agents domain tool. The delegating agent pauses while the target agent runs with its full identity -- persona, plugins, skills, and memory scoping.

Tool Call

agents(action: "delegate", name: "Deal Tracker", prompt: "List all open deals closing this month")

Parameter	Type	Required	Description
`name`	string	yes*	Target agent's display name
`id`	string	yes*	Target agent's ID (alternative to `name`)
`prompt`	string	yes	Task description for the delegated agent
`wait`	boolean	no	Wait for result before continuing (default: `true`). Set `false` for background delegation.
`max_iterations`	integer	no	Maximum agentic loop iterations for the delegated agent (`0` = default)

* One of name or id is required.

Session Isolation

Each delegation creates a separate session keyed as subagent:<parent_id>:<child_id>. The delegated agent:

Loads its own AGENT.md persona and skills
Runs with its own plugin set (from requires.plugins in its agent.json)
Gets its own memory scope -- it does not read the parent's conversation history
Returns a text result to the parent when complete

When to Use Delegation

Scenario	Approach
Agent needs a capability it doesn't have (e.g., calendar access)	Delegate to an agent that has the required plugins
Task requires a different persona or expertise	Delegate to a specialist agent
Background processing while continuing the conversation	Delegate with `wait: false`
Sequential pipeline across multiple agents	Chain delegations in workflow activities

Constraints

The target agent must be installed (appears in agents(action: "list"))
If not already active, delegation auto-activates the target agent
Delegation inherits the parent's cancellation token -- cancelling the parent cancels the child
There is no built-in depth limit, but deep delegation chains consume more tokens and time