Conductor Agents

A Conductor Agent is an agent you author in code — with the Conductor SDK's own Agent class or by bringing an OpenAI Agents / LangChain / LangGraph / Google ADK / Vercel AI / Claude Agent SDK / LangChain4j / LangGraph4j / Semantic Kernel agent — that the server compiles into an ordinary workflow named after the agent. Every LLM turn, tool call, guardrail, human pause and retry is a task in the execution view. Compiled shape (this is what the hand-wired loop in ../examples/ai-agent-loop.md reproduces by hand):

{name}_init_state (SET_VARIABLE)
{name}_loop (DO_WHILE, iteration < maxTurns && !_stop_requested && (toolCalls || LENGTH))
    {name}_llm (LLM_CHAT_COMPLETE) → guardrails → tool-routing SWITCH → [HUMAN approval] → FORK_JOIN_DYNAMIC tools → JOIN → state merge
{name}_synth_output (INLINE)   → outputs {result, finishReason, context, rejectionReason}

An agent execution id is a workflow id — every conductor workflow ... verb (get-execution, terminate, pause, retry) works on it. The deployed agent is a registered workflow definition with metadata.classifier = "AGENT", so schedules, SUB_WORKFLOW, FORK_JOIN and the AGENT task all compose with it.

This page is the contract and the operating manual. Per-language code lives in agent-sdks.md; the AGENT / CANCEL_AGENT / GET_AGENT_CARD task JSON is in workflow-definition.md; the end-to-end walk-through is ../examples/agent-deploy-and-invoke.md.

1. Prerequisite check (run before anything else)

conductor workflow list                                  # server reachable?
conductor agent list                                     # agent runtime on? (table or "No agents found." = yes)
python3 "$CONDUCTOR_API" providers-status                # which LLM providers are configured on the SERVER

CONDUCTOR_API is the path to this skill's scripts/conductor_api.py (export CONDUCTOR_API="<skill-path>/scripts/conductor_api.py"). It is used alongside the CLI for the agent verbs the CLI lacks — provider status, cancel, stop, deploy-from-config — because SKILL.md's allowed-tools has no curl. Set it once per session even when conductor is installed.

• conductor agent list returning 404 / HTML / connection error means the agent runtime is off. conductor server start enables it (--conductor.integrations.ai.enabled=true --agentspan.embedded=true). For a remote server the admin sets conductor.integrations.ai.enabled=true (and agentspan.embedded=true, spring.main.allow-bean-definition-overriding=true). Stop here if it fails — an AGENT task with agentType: "conductor" on such a server fails with the misleading AGENT requires 'agentUrl'.
• Provider keys live on the server (OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, XAI_API_KEY, OLLAMA_BASE_URL, …), never in agent code. Pick a provider/model whose provider reports configured: true (provider names: openai, anthropic, gemini, azureopenai, aws_bedrock, mistral, cohere, grok, perplexity, huggingface, ollama; the Gemini model prefix is google_gemini/).
• MCP / OpenAPI tool discovery is outbound deny-all by default: the admin lists origins in conductor.ai.outbound.allowed-origins (conductor.ai.outbound.allow-private-networks=true for localhost in dev).

2. Which path? (SKILL.md Rule 8)

Tie-breakers: reusable-by-name or scheduled → 2; step order fixed → 1; repo already imports a framework → 3; nothing named → 2 and ask the language. Paths 2, 3, 4 and 4b all end in the same AGENT task; paths 1 and 5 never need an SDK process. Name the path you chose.

Phrasing → path: "workflow that summarizes a ticket with Claude and posts to Slack" → 1 · "agent that looks up orders and issues refunds after approval" → 2 (approval_required=True) · "list MCP tools, pick one, call it" → 1 (add "loop until done" → 2 with mcp_tool(url)) · "run my LangGraph graph durably" → 3 · "call the currency agent at https://agents.example.com" → 4 · "ReAct loop, but each iteration must write an audit row and stop when confidence > 0.9" → 2 first (custom @tool + termination/stop_when), 5 only if JSON-only is a hard requirement.

3. Lifecycle verbs (identical in Python / TypeScript / Java / C#)

Production split: release.py → runtime.deploy(agent) once in CI; worker.py → runtime.serve(agent) as a long-lived service; workflows call the agent by name with the AGENT task.

Agent worker gate (SKILL.md Rule 9). plan()/deploy() return requiredWorkers[]. If it is non-empty, or the framework is passthrough (§6), a serve() process must be running or every execution sits IN_PROGRESS with a tool task stuck SCHEDULED. State which workers are required and which process serves them, every time.

4. Agent definition and run settings

Definition fields (SDK snake_case; wire camelCase in AgentConfig, the body of POST /api/agent/deploy and what every bridge serializes to):

Run settings (per call): prompt, version, session_id, idempotency_key, media[], context{}, timeout, credentials, on_event, RunSettings(model, temperature, max_tokens, reasoning_effort, thinking_budget_tokens). Run wins over definition for model/temperature/max_tokens; max_turns, tools, guardrails, agents, strategy are definition-only (redeploy to change). session_id correlates executions (it becomes contextId) but does not replay earlier turns into a new run — for multi-turn continuity set memory= (ConversationMemory / SemanticMemory) or feed the previous result back in prompt / context.

5. Tools and guardrails

Per-tool knobs on @tool(...): approval_required (→ HUMAN gate before the call), timeout_seconds, max_calls, guardrails=[...], credentials=[...], stateful, retry_count/retry_delay_seconds. The constructors agent_tool(), http_tool(), api_tool(), mcp_tool(), human_tool() do not accept max_calls/timeout_seconds/approval_required (TypeError, verified against SDK 2.0.0) — set the attribute on the returned ToolDef instead (t = agent_tool(child); t.max_calls = 3 → wire maxCalls). ${NAME} placeholders in HTTP headers are resolved server-side. Generated tool task defs get retryCount=2, retryDelaySeconds=2, LINEAR_BACKOFF, responseTimeoutSeconds=3600 — make tools idempotent. Tool description is the routing contract the model reads; write it plainly.

Guardrails: RegexGuardrail(patterns, mode=block|allow, position=Position.INPUT|OUTPUT, on_fail=OnFail.RETRY|RAISE|FIX|HUMAN, max_retries=3, message) (compiles to INLINE, no worker) · LLMGuardrail(model, policy, position, on_fail) (second model, temperature 0) · @guardrail function returning GuardrailResult(passed, message) wrapped as Guardrail(fn, on_fail=...) (compiles to a SIMPLE worker) · external worker by name. Put the strongest guardrail directly before a consequential tool.

Other building blocks (Python names; TS/Java/C# mirror them): termination TextMentionTermination / StopMessageTermination / MaxMessageTermination / TokenUsageTermination composed with & / |; handoff conditions OnToolResult, OnTextMention, OnCondition; CallbackHandler; memory ConversationMemory, SemanticMemory(max_results=...), MemoryStore; code execution CodeExecutionConfig with LocalCodeExecutor / DockerCodeExecutor / JupyterCodeExecutor / ServerlessCodeExecutor, CliConfig; PromptTemplate instructions; scatter_gather(name, worker, model, instructions, ...); skill(path, model) / load_skills(...); Schedule + deploy(..., schedules=[...]); async twins run_async / start_async / stream_async / deploy_async / resume_async; discover_agents(packages); credentials get_secret / resolve_credentials; errors AgentNotFoundError, AgentAPIError, ConfigurationError, CredentialNotFoundError.

6. Framework execution model

In compiled mode the provider key must be on the server; in passthrough mode the key is needed where serve() runs. agentType on the AGENT task is always conductor for any of these once deployed — never the framework id. Framework builders take no max_turns, approval_required or guardrail arguments: the compiled loop runs with the server default maxTurns=100 (ADK LoopAgent.max_iterations, Vercel maxSteps and LangGraph recursion_limit are honored), so bound them from the caller (maxDurationSeconds, run(timeout=), workflow timeout) or wrap a native Agent when you need turn caps or approval gates.

7. Human-in-the-loop contract

An agent pauses when it hits a human_tool, an approval_required tool, or a guardrail with on_fail=HUMAN. From a parent workflow the AGENT task then completes with:

{"executionId": "...", "state": "input-required", "waiting": true,
 "pendingTool": {"taskRefName": "<agent>_approval_human__1", "tool_name": null, "parameters": null,
                 "toolCalls": [{"name": "notify_ops", "args": {"message": "..."}}],
                 "response_schema": {"type": "object", "required": ["approved"], "properties": {"approved": {"type": "boolean"}, "reason": {"type": "string"}}}}}

Verified live: for compiled agents pendingTool.tool_name/parameters are always null — read toolCalls[] (hosted agents, §9, do fill tool_name); text is absent while waiting; a human_tool question lives only in the child HUMAN task's question input (conductor workflow get-execution <executionId>, UI /agentExecutions/{id}).

Branch with a value-param SWITCH on ${ref.output.waiting} (case "true", defaultCase: []), then pick the answer channel by pendingTool.response_schema:

Approve ≠ resume (SKILL.md Rule 12): the AGENT-resume path sends {"result": "<prompt>"}; at an approval gate the compiled agent runs an LLM normalizer (<agent>_approval_human_normalizer) over that text — a model judgment plus a model call — so use the explicit approve channel for gates and keep resume for answers. In a parent workflow the operator completes the HUMAN task (conductor task update-execution --workflow-id <wf> --task-ref-name collect_answer_ref --status COMPLETED --output '{"answer":"..."}') and the resume AGENT task carries prompt: "${collect_answer_ref.output.answer}".

SSE event types (conductor agent stream <id>, GET /api/agent/stream/{id}, Last-Event-ID reconnect): thinking, tool_call, tool_result, handoff, waiting, guardrail_pass, guardrail_fail, error, done, context_condensed, subagent_start, subagent_stop.

8. Operate

Secrets: put names in credentials=["NAME"] (agent or tool) and values in the server store — CONDUCTOR_SECRET_NAME env var on the server (OSS default, conductor.secrets.type=env), /api/secrets when writable, or the Orkes secret manager. Workflow task input can reference ${workflow.secrets.NAME} and ${workflow.secrets.NAME.sub_key} (JSON secret) on OSS and Orkes alike. Never put a value in instructions, prompt, tool config or workflow input (rules D1 / F5).

9. Hosted platform agents (agentType: microsoft-foundry | openai-assistants | bedrock)

The agent stays on its platform; Conductor supplies durability, HITL and cancellation. Common inputs: prompt (required, validated at save), credentials{} with values via ${workflow.secrets.CRED.key} (the secret must be a JSON object for sub-keys; flat value for ${workflow.secrets.KEY}), agentUrl (endpoint + agent in one field, e.g. bedrock://AGENTID/ALIASID?region=us-west-2, https://<res>.openai.azure.com/openai/assistants/asst_x) or rawConfig (Foundry: endpoint, assistantId, apiVersion, scope, surface: assistants|responses|inference, agentVersion, conversation; OpenAI Assistants: assistantId, baseUrl; Bedrock: agentId, agentAliasId, region), executionId (resume), plus the poll knobs. Auth is chosen by which credential keys are present (Foundry: apiKey | client_id+client_secret+tenant_id | managedIdentityClientId | none → default chain; Bedrock: apiKey | accessKeyId+secretAccessKey | roleArn | none). azure-foundry is a deprecated alias of microsoft-foundry; there is no vertex runtime — call Vertex agents with agentType: "a2a".

Function tools the platform cannot run come back as pendingTools. autoRunTools is on by default: the AGENT task stays IN_PROGRESS, schedules each call as a SIMPLE task named after the tool (inputs = the tool's arguments flattened + _toolCallId, _toolName, _agentExecutionId; tasks are optional), and resumes the agent with the results — so a worker registered for get_revenue serves the agent's get_revenue tool with no configuration. maxToolTurns (default 10) bounds the rounds; toolTaskNames remaps names; autoRunTools: false hands the calls back (waiting: true + pendingTools) for a manual resume with toolResults keyed by tool_call_id. Outputs add pendingTools, executedTools (platform-run built-ins), toolDispatchId. Bedrock has no status or cancel API (terminal on first call); Foundry runs expire 10 minutes after creation, total.

10. Schedule a deployed agent

The agent is a workflow named after it, so the ordinary scheduler applies (schedules.md): conductor schedule create -n <agent>-<purpose> -c "0 0 2 * * ?" -w <agent> -i '{"prompt":"..."}' [-p] (six-field Quartz cron). Pin --version for production callers. Something must be serve()-ing the agent's worker tools when it fires, or runs pile up unserved.

11. Test

Ladder: unit → trace assertions (mock/replay) → live correctness evals (nightly) → semantic evals → production monitoring (conductor agent execution, token usage on /agent/execution/{id}).

12. Gotchas (all verified against source)

• AGENT conductor branch takes name, not agentName (agentName is an output field / REST alias only). prompt is required on start and on resume.
• agentType is an execution mode: conductor, a2a (default when omitted), microsoft-foundry, openai-assistants, bedrock. A framework name is never valid. Omitting it with name yields AGENT requires 'agentUrl'.
• Read results at ${ref.output.text} and ${ref.output.output.result} (two .outputs) — output is the compiled workflow's outputParameters map.
• model must be provider/model. CONDUCTOR_AGENT_LLM_MODEL is read only by the Python OpenAI-compat Runner and SDK examples — not SDK configuration.
• Cancellation surfaces as task status CANCELED and state: canceled (not FAILED). Parent TERMINATE propagates to the child in the embedded runtime.
• deploy() registers only; run() is not a deployment; requiredWorkers non-empty or passthrough → serve() must run.
• conductor deploy (CLI) shells to a module that does not ship with conductor-python — use SDK deploy(). There is no conductor agent cancel|stop|deploy.
• Java artifact is org.conductoross:conductor-client-ai (not conductor-ai). C# conductor-ai* packages are a preview (project reference). TS SDK 4.x reads CONDUCTOR_SERVER_URL / CONDUCTOR_AUTH_*; C# per its README.
• Python LangChain: take create_agent from conductor.ai.agents.langchain, not langchain.agents.
• TS Vercel AI: the SDK auto-detects AI-SDK ≤ 4 tools (parameters + execute, named from the description); AI-SDK 5+ inputSchema tools are not detected — use the native tool(execute, {name, description, inputSchema}) with the same Zod schema.
• /api/skills/** needs agentspan.skills.enabled=true; /api/a2a/** needs conductor.a2a.server.enabled=true (+ agentspan.embedded=true) — off unless set.
• conductor workflow create drops workflow metadata; register A2A-exposed workflows (metadata.a2a.enabled) via POST /api/metadata/workflow?overwrite=true. The workflow facade delivers the message as input _a2a_text (+ _a2a_message_id, _a2a_context_id, merged data parts) and returns the workflow output as a data artifact; deployed agents are called at /api/a2a/agent/<name> (they need prompt, which the workflow facade never sets).
• a2a pushNotification: true silently falls back to polling when conductor.a2a.callback.url is unset.
• ${workflow.secrets.X} is not resolved for task input externalized to payload storage (large inputs).
• Python serve() / run() start worker processes with the spawn start method on macOS and Windows: call them under if __name__ == "__main__": (a bare module-level call re-imports the script in every child and fails with An attempt has been made to start a new process before the current process has finished its bootstrapping phase).
• Don't name your package directory agents/ without an __init__.py — the OpenAI Agents SDK package is also called agents, and a namespace directory loses to it on import.