Invoke agent
invoke_agentSend a message to a hosted agent and get its reply, with state preserved for future calls. Use for long-running, multi-step tasks by polling the returned run ID.
Instructions
Send a message to an agent and get its reply. Use this for work that should outlive a single request: files written now and read next week, software installed once and reused, a repo kept checked out, or a long job handed off and read later. Do not use it for a stateless snippet you can run inline, with no state worth keeping: a plain code sandbox is cheaper and faster for that. By default waits up to ~25s for the turn to finish and returns the assistant's reply; if it is still running by then it returns a run_id with status "running" to poll via get_run_result. Agent turns can take minutes (research, multi-step or tool-heavy work). This call blocks your own turn while it waits, and no MCP client backgrounds it — so if the user is not waiting on this reply, or you expect a long turn, pass wait=false to get a run_id back immediately and poll get_run_result on your own cadence instead of holding the call open. Running an agent spends credits, and an account's plan caps how many runs it may have in flight at once across all its agents (over the cap returns 429; wait for a run to finish and retry). Turns on one agent are not queued for you. Pass idempotency_key when you might retry this call: a retry carrying the same key returns the original run instead of starting and billing a second one. If the run pauses on a human-input request it returns status "awaiting_input" with the pending request details inline (respond with answer_pending_input). Every result also carries a "url" that opens this run's exact session in the web app, so a human can go read it.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| wait | No | Wait (up to ~25s) for the turn and return the reply (default true). Set false to return a run_id immediately and poll get_run_result — prefer this for long or tool-heavy turns so the call doesn't block your own turn. | |
| message | Yes | The message to send to the agent. | |
| agent_id | Yes | The agent's UUID. | |
| session_id | No | Optional thread/session id to continue an existing conversation (a previous invoke_agent or get_run_result result carries it as "session_id"); omit to start a new one. | |
| idempotency_key | No | Optional retry guard: a string you generate for this attempt. Re-sending the same key with the same agent and message within 24h returns the ORIGINAL run instead of starting a second one. Reusing a key with a different message is an error. | |
| max_turn_tokens | No | Optional cumulative cache-weighted token ceiling for this turn (0 or omitted uses forge's default; maximum 5,000,000). The agent reserves its final 2% for a tool-free wrap-up. |