agent
Processes diverse tasks by intelligently selecting a Grok model and activating built-in tools including web search and code execution, with optional session persistence.
Instructions
Run the unified UniGrok agent on any task. This is the headline entry point — use it by default for anything nontrivial instead of picking a specialized tool.
It auto-routes across Grok models (planning model for reasoning-heavy tasks, coding model otherwise), gives the model its full action space on every request — xAI server-side web search, X search, and sandboxed code execution plus local file, git, and test tools — and lets the model decide for itself whether to act. Pass a session name and it remembers prior turns, including tool observations, so multi-step work continues across calls. When the client requests progress (MCP progressToken), depth and tool progress is reported live via the injected FastMCP context.
Args:
task: The goal, question, or task for the agent.
session: Optional session name. Persists conversation history and tool
traces so later calls can continue the work.
mode: "auto" (default) self-routes; "fast" forces a single toolless
completion for trivial prompts; "reasoning" pins the planning
model; "thinking" runs the agent loop plus a schema-enforced
reflection review for the hardest tasks (slowest, most expensive);
"research" runs multi-agent research on the planning model
(agent_count from UNIGROK_RESEARCH_AGENT_COUNT, 4 or 16) with
inline citations requested — sources come back under citations.
model: Optional Grok model id. Leave unset to let routing choose.
require_reasoning_level: Minimum required Grok reasoning level (low, medium, high).
Returns: AgentResult containing execution metadata and responses.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | auto | |
| task | Yes | ||
| model | No | ||
| session | No | ||
| require_reasoning_level | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| why | No | Router decision trace (Grok-native). | auto |
| text | No | Human-formatted output (includes footers, citations, cost summary). | |
| model | Yes | Actual executing model ID (e.g. 'grok-4.5'). | |
| plane | No | API | |
| route | Yes | High-level route (fast/agentic/research/etc.). | |
| trace | No | Multi-agent step trace (for grok_agent research mode). | |
| tokens | No | Total tokens consumed. | |
| profile | No | Internal routing profile. | |
| cost_usd | No | Exact USD cost from xAI billing metadata. | |
| degraded | No | True if fallback occurred. | |
| response | Yes | Raw model output or primary content. | |
| citations | No | Native xAI/X citations with URL + snippet. | |
| latency_sec | No | ||
| finish_reason | No | unknown | |
| reasoning_effort | No | Grok 4.5+ native reasoning level. |