> ## Documentation Index
> Fetch the complete documentation index at: https://www.sikaru.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Managed Agents, Runs, and Tools

> Run Sikaru-managed agents, stream durable runs, resume executions, and register product-owned tools for continual learning workflows.

Sikaru agents are managed agents: Sikaru owns the durable run lifecycle and managed harness, while your product owns the user experience, private tools, credentials, and approvals.

Managed runs create the experience data Sikaru needs for continual learning. Failures, user feedback, operator corrections, eval results, and successful outcomes become evidence for reviewed behavior updates that improve reliability and user satisfaction over time.

## Choose the right entrypoint

| Method         | Use it when                                                                                                                                            |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `respond(...)` | You want the simplest request-response path. It streams events internally, executes local tools, records the experience, and returns the final output. |
| `run(...)`     | You want manual event control, custom rendering, or explicit tool-result handling.                                                                     |
| `stream(...)`  | You want an iterator over run events while the SDK still completes local tool calls.                                                                   |
| `resume(...)`  | You need to reconnect to a durable run after a deploy, network interruption, or client reconnect.                                                      |

## Respond

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    support = sikaru.agent("support", tools=[search_crm])

    result = support.respond(
        messages="Draft a retention plan for Acme.",
        user="user_123",
        conversation="conv_123",
    )

    print(result.output)
    print(result.run.id)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```ts theme={null}
    const support = sikaru.agent("support", {
      tools: { searchCrm },
    });

    const result = await support.respond({
      messages: "Draft a retention plan for Acme.",
      user: "user_123",
      conversation: "conv_123",
    });

    console.log(result.output);
    console.log(result.run.id);
    ```
  </Tab>
</Tabs>

## Stream manually

Use `run(...)` when the product UI needs every event or when you want to decide how tool requests are handled.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    run = support.run(
        messages="Draft a support plan.",
        user="user_123",
        conversation="conv_123",
    )

    for event in run.stream():
        if event.event_type == "run.tool_call.requested":
            run.complete_local_tool(event)
        render_event(event)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```ts theme={null}
    const run = await support.run({
      messages: "Draft a support plan.",
      user: "user_123",
      conversation: "conv_123",
    });

    for await (const event of run.stream()) {
      if (event.eventType === "run.tool_call.requested") {
        await run.completeLocalTool(event);
      }
      renderEvent(event);
    }
    ```
  </Tab>
</Tabs>

## Resume a durable run

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    run = support.resume("run_123", after=42)

    for event in run.stream():
        render_event(event)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```ts theme={null}
    const run = await support.resume("run_123", { after: 42 });

    for await (const event of run.stream()) {
      renderEvent(event);
    }
    ```
  </Tab>
</Tabs>

## Local tools

Local tools run inside your product process. They are the right fit when a capability needs your application database, service clients, policy checks, or private credentials.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    @tool("ticket.create", description="Create a support ticket.")
    def create_ticket(title: str, account_id: str):
        return ticket_client.create(title=title, account_id=account_id)

    support = sikaru.agent("support", tools=[create_ticket])
    ```
  </Tab>

  <Tab title="TypeScript">
    ```ts theme={null}
    const createTicket = tool({
      capability: "ticket.create",
      description: "Create a support ticket.",
      inputSchema: { type: "object" },
      execute: async (input) => createTicket(input),
    });

    const support = sikaru.agent("support", {
      tools: { createTicket },
    });
    ```
  </Tab>
</Tabs>

## Provider tools

Provider tools are references to product-owned brokers. Use them when a separate service handles capabilities such as MCP servers, Composio connectors, or remote tool gateways.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    support = sikaru.agent(
        "support",
        tools=[
            tool.provider("tp_gmail", "gmail", skills=["skills/gmail/skill.md"]),
            tool.mcp("tp_linear_mcp", "linear"),
            tool.composio("tp_composio", "slack"),
        ],
    )
    ```
  </Tab>

  <Tab title="TypeScript">
    ```ts theme={null}
    const support = sikaru.agent("support", {
      tools: [
        tool.provider("tp_gmail", "gmail", { skills: ["skills/gmail/skill.md"] }),
        tool.mcp("tp_linear_mcp", "linear"),
        tool.composio("tp_composio", "slack"),
      ],
    });
    ```
  </Tab>
</Tabs>

## Run inputs

Each managed run should include stable product identifiers.

| Field          | Meaning                                                  |
| -------------- | -------------------------------------------------------- |
| `user`         | Product user ID.                                         |
| `conversation` | Conversation, thread, ticket, or session thread ID.      |
| `tenant`       | Optional tenant or account scope.                        |
| `trace`        | Optional trace ID when your product already created one. |
| `job`          | Optional background job ID.                              |
| `correlation`  | Optional product correlation ID for joining logs.        |

<Note>
  Keep user-facing artifacts and audit logs in your product. Sikaru receives enough context to run, learn, and propose reviewed changes without becoming your system of record.
</Note>