Agent DocsDeveloper documentation
Builder Guide

Calling Agents & Tools

Invoking agents under policy with call_agent and grants

Calling agents & tools

Audience: Customer developers and admins. How a workflow invokes a platform agent (or tool), and why those calls are governed by policy.

Workflows orchestrate; agents reason. When a step needs judgement — classify a document, assess compliance, draft a response — your workflow calls an agent and uses the result. Because a workflow is a governance principal, every such call is checked against policy.

call_agent

from workflow_sdk import call_agent

result = await call_agent(
    "agent-finance-compliance",          # the agent to invoke
    source_agent_id=SOURCE_PRINCIPAL_ID, # this workflow, as the calling principal
    message="Assess this vendor for compliance risk.",
    context={"vendor": vendor.model_dump()},
)

The call goes through the platform gateway, which authorises it and runs the agent under full governance and tracing. There is a matching call_tool for invoking a registered tool directly.

Call agents from activities, not from workflow code directly — network calls are side effects, and side effects belong in @activity.defn functions. The shipped template does exactly this: agent_review_activity calls call_agent and returns a typed result the loop stores in state.

Calls are governed: declare the grant

A workflow may only call an agent it has been granted. There are two sides to the grant:

  1. You declare intent. List the agent in your workflow's WorkflowRequirements.invokes:

    WORKFLOW_REQUIREMENTS = {
    "ReferenceReviewWorkflow": WorkflowRequirements(
        workflow_id="ReferenceReviewWorkflow",
        invokes=["agent-finance-compliance"],   # <- the grant you're requesting
        input_model=ReviewInput,
    ),
}

    At registration, this emits a grant edge from your workflow to the agent.

  2. The agent opts in. The target agent must allow being invoked by a workflow (its invocableBy policy includes workflows). This is an admin-side setting on the agent — a workflow can't call an agent that hasn't opened itself to workflow callers.

If either side is missing, the call is denied at runtime: call_agent raises RuntimeError("Policy denied: …"). This is deliberate — a workflow can't quietly reach an agent it wasn't granted.

Scroll to zoom · Drag to pan · 100%

For admins

Granting a workflow access to an agent is a governance decision, not just a code change:

  • The invokes declaration is a request; approving the policy (and the agent's invocableBy opt-in) is what actually authorises it.
  • Every call is traced and attributed to the workflow principal, so you can audit which workflows used which agents.
  • Keep invokes minimal — a workflow should be granted only the agents it genuinely needs.

Related