Agent Integration Patterns

An agent drives InvesTeam over MCP with one pattern: submit → get an id → poll. Submit tools kick off work and return a session_id; results come only from poll tools. One session_id threads the whole pipeline, and every status enum is open — treat an unknown value as non-terminal and keep polling. Output is decision-support analysis, not investment advice.

How does the agent loop work?¶

The agent creates a brief, answers any clarifications, polls the brief to completion, then — where the committee tools are enabled — convenes and reads the run. One session_id co-keys every stage.

create_brief(input)                          -> {session_id, status}
  |- if needs_clarification / awaiting_answers:
  |    answer_clarifications(session_id, answers)
  |- poll get_brief(session_id) until status is completed or rejected
  -> convene_committee(session_id, brief)                 [gated]
  -> poll get_execution(session_id) until completed|failed [gated]
  |    get_transcript(session_id, after=latest_seq)        [gated]
  -> poll get_analysis(session_id) until the synthesis returns

The gated steps register only when their server-side flags are on. Branch on the tools your client actually lists rather than assuming the full set is present. There is deliberately no server-side "poll until done" tool — the agent owns the cadence.

How often should an agent poll InvesTeam?¶

Poll every two to three seconds. The server applies a per-(key, session) minimum interval between polls of the same stage as defense-in-depth: poll faster than that floor (default 750ms) and the tool returns a rate_limited result without an upstream call. A ~2–3s cadence stays clear of it. This poll guard is not the authoritative rate limit — that lives on the API — so also honor a 429 from the API: it carries retry_after_seconds, and the agent should wait that interval rather than hammering the quota.

When should an agent stop polling?¶

Stop at a terminal status. A brief is terminal at completed or rejected; a committee execution is terminal at completed or failed; the analysis is terminal once its synthesis payload returns. For the transcript, drain then stop: once get_execution is terminal, do one final get_transcript read to catch the last turns, then stop polling. Because every status enum is open, treat any value you do not recognize as non-terminal and keep polling — a new status should never strand the loop.

What does a 404 mean, and when should the agent retry?¶

A 404 means different things on different tools, and the right response differs. On a poll tool it is the not-ready sentinel — { "ready": false } — meaning "valid id, stage not producing output yet"; keep the same session_id and poll again. On an ownership tool (get_brief, create_brief, answer_clarifications) a 404 is a not_found error — a bad or foreign id — which the agent should not retry; fix the id instead.

When should an agent NOT retry?¶

Retry only what is retryable. An error result carries a retryable flag — retry with back-off only when it is true. Do not retry a not_found (a bad id), an unauthorized (fix the key), a forbidden (add the missing scope, e.g. pipeline:write), or a bad_request (fix the input) — retrying these just burns calls. For a rate_limited or 429, back off and respect retry_after_seconds.

How does the agent avoid double-submitting?¶

Always pass an idempotency_key on a mutating tool (create_brief, answer_clarifications, and the gated convene_committee). It is forwarded as the Idempotency-Key header; when omitted, a stable key is synthesised from the tool, session id, and canonical input, so a retry carries a consistent key.

Does the agent need to handle the disclosure?¶

Yes. Every tool that returns AI-generated output includes a disclosure object, and the agent must pass it through to the end user unchanged. The obligation also rides in each such tool's description so it reaches the agent's context at wiring time:

What's next?¶

See the MCP Tool Catalog for each tool's exact inputs and outputs, and Connect to Claude or Connect Other Clients to wire up. The same loop in plain HTTP is the async submit → poll model and the pipeline walkthrough.