Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ntropii.com/llms.txt

Use this file to discover all available pages before exploring further.

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

ArgTypePurpose
agent_idstr (UUID)The Ntropii agent id — NOT the host platform’s native id. Resolved against the workspace registry to look up kind + external_ref.
inputdict[str, Any] | strThe 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_slugstrRequired for any session that produces files (it’s the data-plane connection target).
entity_slugstr | NoneThreads onto persisted ingest.submitted_documents rows for queryability.
task_idstr | NoneWorkflow id (root, stripped of any :step:slug suffix). Threads onto persisted rows.
poll_interval_secondsfloatDefault 5.0. How often to poll session status.
max_poll_secondsfloatDefault 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 workflow.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:
KindProviderNotes
claude_managedAnthropicManagedAgentProviderProduction. See Claude Managed Agents.
copilot_agentTBDPhase 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 @ui_step method.