Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
agent
What it is
Part of AI: the model-agnostic turn runner every AI surface in the product builds on — agent sessions, document AI, and background AI features all run a turn through this crate's loop, with a shared model/speed vocabulary and usage metering.
Start here
src/agent_loop.rs:AgentLoop/Session— runs a turn, dispatches tool calls, loops until a final response.src/model/: provider adapters (anthropic.rs,openai.rs,gemini.rs) behindmodel/router.rs, pluspredefined_model.rs/speed.rs(the product-facing model/speed vocabulary) andmetering.rs(usage recording hook intoai_usage).AgentLoop::with_streamed_tool_callsopts hosts into early tool-call announcements and argument deltas; the accumulator persists only final calls.src/stream.rs:StreamPart/ChatCompletionStream, the wire shape callers consume.src/completion.rs: one-shot, non-looping completions (no tools).src/tool_result_limit.rs:ToolResultLimitcuts tool results too long for the model (in the hook and on replay throughto_rig_messages_limited) and keeps them for theReadToolResultpager tool; opt in withAgentLoop::with_tool_result_limit.src/structured_output.rs: prompted JSON generation with offline schema preflight and result validation; external schema references are rejected.src/tool_media.rs: promotes explicit top-levelmodelMediaresults to bounded native PNG blocks for both tool adapters and history replay; nested content stays JSON and remote image URLs are rejected. Keep the public JSON envelope in streamed results/history while excluding pixels from model text.
Scope
- Owns: the turn loop, provider routing/model selection, streaming parts, and metering integration.
- Not here: tool definitions and schemas →
ai_toolset,ai_tools; usage pricing/billing →ai_usage,ai_billing.
Boundaries
- Depends on:
ai_usage(metering),ai_toolset(tool adapter trait),attachment,genai_telemetry,prompt,rig-core/rig-agent. - Used by:
agent_inmem,ai_tools,ai_projections(agentfeature), and most AI-surface crates that run a turn (directly or viaai_tools).
Recipes
- Add a model:
src/model/predefined_model.rs(enum variant) →src/model/router.rs(dispatch) → provider adapter insrc/model/→ pricing inai_usage. - Add a stream part / tool-call shape change:
src/stream.rs→src/convert.rs(rig message conversion) →src/accumulator.rs(accumulation across chunks).
Checks
cargo test -p agent(SQLX_OFFLINEunset).
Gotchas
- A
Sessionlives for one turn. Before its first request it reloads the catalog tools the history called or loaded, readingSearchTools/LoadToolsresults throughai_toolset::tool_search::tools_loaded_by; change those response types there, not inai_tools. rig-core/rig-agentare pinned exact versions (not workspace deps); bump both together and checktest-utilsfeature compatibility.AgentLoop::with_provider_api_keyrekeys only the loop's own model calls (native Anthropic/OpenAI); call it afterwith_model. Tools andcomplete*still use the deployment's keys.
Related
- Rules:
.agents/rules/rust/architecture.md· Skill:upgrade-model
Canvas native image results remain native through tool output and history replay. Compatible Chat Completions provider requests omit those unsupported tool images with an explicit explanation; they never stringify encoded pixels into prompts. Model-request telemetry records native image counts without requiring content capture; image pixels remain excluded by genai_telemetry.