Integration notes for coding agents
View SourceThis is a compact entry point for agents implementing an application using ExAgent. It describes public APIs, result shapes and application responsibilities.
Read only what the task needs
- Check Supported features and limits and the application's dependency version.
- Read Getting started for the result and environment contract.
- Select the task guide below and inspect its linked module/function docs.
- Implement with public APIs, verify locally with TestModel, then qualify any new real-backend combination explicitly.
The generated site's llms.txt indexes pages and modules. Each page also has a
Markdown representation, for example getting-started.md beside
getting-started.html. Use those files for retrieval rather than scraping the
sidebar. In a source clone,
paths below are relative to docs/guides/; generated ExDoc pages are flattened.
API map
| Task | Entry | Read |
|---|---|---|
| One-shot execution | ExAgent.new/1, run/3 | Getting started |
| Lazy streaming | ExAgent.run_stream/3 | Runtime |
| Define tools | ExAgent.Tools, Tool.new/1 | Tools and output |
| Typed output | output: MyEmbeddedSchema, output_mode: | Tools and output |
| Skills loaded on demand | ExAgent.new(skills:), Skills.from_dir!/2, Skill.new/1 | Skills |
| Provider/model | Model.resolve/2, Models.ReqLLM.new/1 | Models |
| Qualified OpenRouter routing | tool_profile: :openrouter_chat_tools_v1, bounded provider_options: | Models |
| Conversation owner | AgentSupervisor.start_agent/1, Server.chat/3 | Runtime |
| UI updates | Event.agent_topic/2, PubSub.subscribe/2 | Runtime |
| Checkpoint | store:, Server.checkpoint/1, Session.checkpoint/1 | Durability |
| Persisted approval | Continuation.get/2, decide/4, ExAgent.resume/3 | Durability |
| Shared-state turns | Session, Session.Participant, TurnPolicy | Coordination |
| Typed durable shared state | Host Session.StateCodec, shared_state_codec: | Coordination |
| Delegation | Coordination.delegation_tool/2, ExAgent.run_child/4 | Coordination |
| Durable sequence/router/parallel | Coordination.Composition, Coordination.Flow | Coordination |
| MCP tools | MCP.Client.start_link/1, tools/1, close/1 | MCP |
| Retrieval/jobs | Host-owned integration recipes | Documentation map |
| Traces and mixed ReqLLM calls | ExAgent.Observability.OpenTelemetry, ExAgent.Observability.ReqLLM.attach/1 | Observability |
| Long-lived tracing cleanup | Supervise ExAgent.Observability.ReqLLM.Maintenance; set a finite processor max_exporter_restarts when needed | Observability |
| ReqLLM metrics | ReqLLM.attach(metrics: [models: [...]]); host experimental API/SDK 0.6 and reader | Observability |
| Disposable native HTTP/gRPC export | Application-owned VM recipe with finite batch and deadline | Isolated transport |
| Offline verification | %ExAgent.Models.Test{script: ...} | Testing |
| Unexpected behavior | Sanitized reason + relevant boundary | Troubleshooting |
Preserve these contracts
- Result:
{:ok, result}or{:error, %ExAgent.RunError{reason: reason, partial: result}}for operational run failures. Invalid construction can raise.result.outputis final only on success. Do not serialize live results wholesale. - Stream: provisional
{:delta, text}events, then{:result, result}or{:error, error}. Enumerate once; own and close suspended continuations. - Model: official stock ReqLLM. Catalogue resolution alone does not qualify tools/streaming/native output. Configure an explicit compatible profile.
- Tools: validate before invocation. Keep results JSON-portable. A tool timeout or failure is not evidence that its external effect never occurred.
- Authority: derive namespace/actor from authenticated host state. Ancestor permissions and budgets constrain children. Prompt text cannot grant approval.
- Accounting: exact host counters differ from normalized/reported tokens and estimated cost. Parent totals include descendants. Unknown cost is not zero.
- Persistence: ACK requires confirmed save. Dirty blocks mutations; checkpoint retry saves data only. ETS is ephemeral. Resume needs trusted templates and bindings. A typed Session codec is supplied by the host on every start; stored data never selects its module. Keep encode/decode pure and validate application data.
- Recovery: reconcile uncertain effects explicitly. Do not turn every error, queue retry or restored message history into a fresh run.
- Observability: optional, host-owned SDK/exporter, content off by default. Use the integrated ReqLLM bridge for mixed applications; attach once at startup and maintain its upstream tracking TTL, optionally with the supervised child. The TTL must exceed live request durations; restart budgets reset per instance. Metrics require an explicit bounded model allowlist and a host-owned reader; their token counts retain normalized quality. The default tracer follows a restarted SDK; replace any explicit tracer when replacing its provider. Sampled spans are not a billing ledger or guaranteed durable audit record.
Verify the relevant boundary
Test ordinary app behavior with TestModel. For tools, assert real invocation and returned parts; for runtime, match namespace/request IDs; for persistence, assert the confirmed transition and duplicate-attempt behavior. Run the app's own tests. Changes to a real provider profile need separate opt-in acceptance and credentials supplied by the host. Passing offline cases must not be reported as live compatibility.
If upgrading 1.x, read Migration before copying an old example.