Managed Agents, Runs, and Tools

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

Python
TypeScript

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)

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);

Stream manually

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

Python
TypeScript

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)

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);
}

Resume a durable run

Python
TypeScript

run = support.resume("run_123", after=42)

for event in run.stream():
    render_event(event)

const run = await support.resume("run_123", { after: 42 });

for await (const event of run.stream()) {
  renderEvent(event);
}

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.

Python
TypeScript

@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])

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 },
});

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.

Python
TypeScript

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"),
    ],
)

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"),
  ],
});

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.

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.

​Choose the right entrypoint

​Respond

​Stream manually

​Resume a durable run

​Local tools

​Provider tools

​Run inputs

Choose the right entrypoint

Respond

Stream manually

Resume a durable run

Local tools

Provider tools

Run inputs