ntro.workflow.agents

ntro.workflow.agents is the SDK surface for invoking a registered external agent from inside a runbook step. For the registration lifecycle, see Register agents.

Install

pip install 'ntro[workflow]'

The agents module is part of the [workflow] extra.

`invoke`

from ntro.workflow.agents import invoke

result = await invoke(
    agent_id,
    *,
    input,
    tenant_slug=None,
    entity_slug=None,
    task_id=None,
    poll_interval_seconds=5.0,
    max_poll_seconds=1800.0,
)

Invokes a registered external agent and returns its result.

Arguments

Arg	Type	Purpose
`agent_id`	`str` (UUID)	The Ntropii agent id — NOT the host platform’s native id. Resolved against the workspace registry to look up `kind` + `external_ref`.
`input`	`dict[str, Any] \| str`	The agent’s kickoff payload. Dicts are JSON-serialised before being sent as the user message; strings pass through. Periods, dates, and other temporal context belong inside this dict (they’re data, not routing).
`tenant_slug`	`str`	Required for any session that produces files (it’s the data-plane connection target).
`entity_slug`	`str \| None`	Threads onto persisted `ingest.submitted_documents` rows for queryability.
`task_id`	`str \| None`	Workflow id (root, stripped of any `:step:slug` suffix). Threads onto persisted rows.
`poll_interval_seconds`	`float`	Default `5.0`. How often to poll session status.
`max_poll_seconds`	`float`	Default `1800.0` (30 min). Hard cap on polling before returning a `failed` result.

Returns

AgentResult (pydantic):

class AgentResult(BaseModel):
    agent_id: str
    session_id: str
    status: Literal["completed", "failed", "terminated"]
    output_text: str | None
    output_files: list[AgentOutputFile]
    error: str | None
    raw: dict | None  # provider-specific session payload


class AgentOutputFile(BaseModel):
    document_ref: str    # FK into ingest.submitted_documents
    filename: str
    content_type: str
    size_bytes: int
    source: str          # always "agent_output:<agent_id>"

Lifecycle

invoke(agent_id, …)
   │
   ├─ 1. Resolve agent           workspace API → {kind, external_ref}
   │
   ├─ 2. Pick provider           kind → AnthropicManagedAgentProvider, …
   │
   ├─ 3. Compose input           dict → JSON serialise
   │
   ├─ 4. Start session           provider.start_session(...)
   │
   ├─ 5. Poll to terminal        provider.poll_session(...) until terminal
   │
   ├─ 6. List session files      with backoff for index-eventual-consistency
   │
   ├─ 7. Persist each file       ntro.ingest.insert_submitted_document(
   │                              source='agent_output:<agent_id>', ...)
   │
   └─ 8. Return AgentResult      includes output_files refs

Activities calling invoke should give it a generous start_to_close_timeout — Anthropic Sessions can run for tens of minutes for complex agents.

await runbook.execute_activity(
    draft_auditor_handover,
    AuditHandoverInput(...),
    start_to_close_timeout=timedelta(minutes=45),
)

File passback

Files persisted to the tenant data plane via invoke always carry source = 'agent_output:<ntropii-agent-id>'. They sit alongside user-uploaded documents in ingest.submitted_documents and are downloadable from the task UI like any other artefact. The period column on the row is NULL for agent outputs — period is a runbook-domain concept (some runbooks have it, some don’t), not part of the invocation contract. Runbooks that want the column populated should update the row downstream.

Polling semantics

The Anthropic Sessions API surfaces three terminal states: completed, failed, terminated. The adapter also treats idle with positive output_tokens as completed (the agent finished its work and went idle). The /v1/files index is eventually-consistent with session termination — files written in the agent’s final tool call may not appear in the listing for ~1-2s after the session goes terminal. The adapter retries the listing up to 5 times at 1s intervals so a single empty response doesn’t drop a real file.

Providers

Built-in:

Kind	Provider	Notes
`claude_managed`	`AnthropicManagedAgentProvider`	Production. See Claude Managed Agents.
`copilot_agent`	TBD	Phase 3 — placeholder in the dispatch shell.

To add a provider, implement the ManagedAgentProvider protocol (start_session, poll_session, list_session_files, download_file) and wire it into ntro/workflow/agents/_config.py.

Register agents

Registration lifecycle (build → register → reference).

Claude Managed Agents

End-to-end walkthrough for the Anthropic adapter.

ntro.ingest

insert_submitted_document — the persistence function invoke uses.

Build runbooks

The runbook-side of invoke, inside a @runbook.step method.

Get Started

Tooling

Building workflows

Ntro SDK

API Reference

Deploy & Run

ntro.workflow.agents

Install

`invoke`

Arguments

Returns

Lifecycle

File passback

Polling semantics

Providers

Register agents

Claude Managed Agents

ntro.ingest

Build runbooks

​Install

​invoke

​Arguments

​Returns

​Lifecycle

​File passback

​Polling semantics

​Providers

​Related

Register agents

Claude Managed Agents

ntro.ingest

Build runbooks

Install

`invoke`

Arguments

Returns

Lifecycle

File passback

Polling semantics

Providers

Related