|
| 1 | +--- |
| 2 | +name: interchange-agents |
| 3 | +description: Build and embed an Interchange agent in code with tools, inference sources, and tests. Load when writing createAgent or defineAgent code. |
| 4 | +user-invocable: false |
| 5 | +--- |
| 6 | + |
| 7 | +# Interchange agents |
| 8 | + |
| 9 | +Use `@intx/agent` when you want an agent inside your own program, CLI, or service. No hub is required. |
| 10 | + |
| 11 | +## Minimal agent |
| 12 | + |
| 13 | +```ts |
| 14 | +import { |
| 15 | + createAgent, |
| 16 | + createDefaultDirectorRegistry, |
| 17 | + createStaticCredentialResolver, |
| 18 | + defineAgent, |
| 19 | + type BaseEnv, |
| 20 | +} from "@intx/agent"; |
| 21 | +import { noopAuditStore, permissiveAuthorize } from "@intx/agent/testing"; |
| 22 | +import { createIsogitStore } from "@intx/storage-isogit/node"; |
| 23 | + |
| 24 | +const storage = await createIsogitStore(contextDir); // directory must exist |
| 25 | +const def = defineAgent({ |
| 26 | + id: "my-agent", |
| 27 | + systemPrompt: "You are a helpful assistant.", |
| 28 | + tools: [], |
| 29 | + capabilities: [], |
| 30 | + inference: { sources: [{ provider: source.provider, model: source.model }] }, |
| 31 | +}); |
| 32 | +const env: BaseEnv = { |
| 33 | + sources: [source], // { id, provider, baseURL, credentialId, model } |
| 34 | + defaultSource: source.id, |
| 35 | + storage, |
| 36 | + workdir: contextDir, |
| 37 | + audit: noopAuditStore(), |
| 38 | + authorize: permissiveAuthorize(), |
| 39 | + directors: createDefaultDirectorRegistry(), |
| 40 | + readCurrentMaterial: createStaticCredentialResolver({ |
| 41 | + [source.credentialId]: apiKey, |
| 42 | + }), |
| 43 | +}; |
| 44 | +const agent = await createAgent(def, env); |
| 45 | +try { |
| 46 | + const result = await agent.send(prompt); |
| 47 | + if (result.type !== "reply") |
| 48 | + throw new Error(`suspended on ${result.correlationId}`); |
| 49 | + console.log(result.reply); |
| 50 | +} finally { |
| 51 | + await agent.close(); |
| 52 | +} |
| 53 | +``` |
| 54 | + |
| 55 | +- `send()` returns a union. Anything other than `reply` means the agent suspended on a gate (approval, pending tool) and needs an inbound message with that `correlationId`. |
| 56 | +- `permissiveAuthorize` and `noopAuditStore` are test stubs. A product supplies a real `authorize` built on `@intx/authz` and a real audit store. |
| 57 | +- Re-running on the same `contextDir` resumes the conversation. Clone the directory and reset `HEAD` to rewind. |
| 58 | + |
| 59 | +## Tools |
| 60 | + |
| 61 | +```ts |
| 62 | +import { defineTool } from "@intx/agent"; |
| 63 | +import { posix, type PosixToolEnv } from "@intx/tools-posix/sidecar-bundle"; |
| 64 | + |
| 65 | +let disposeTools: (() => Promise<void>) | undefined; |
| 66 | +const posixTools = defineTool<PosixToolEnv>({ |
| 67 | + id: posix.id, |
| 68 | + requires: posix.requires, |
| 69 | + definitions: posix.definitions, |
| 70 | + factory: (env) => { |
| 71 | + const b = posix(env); |
| 72 | + disposeTools = b.dispose; |
| 73 | + return b; |
| 74 | + }, |
| 75 | +}); |
| 76 | +// def.tools = [posixTools]; env gains toolCwd (tree the model edits) |
| 77 | +``` |
| 78 | + |
| 79 | +`toolCwd` is what the model reads and edits. `workdir` is the isogit storage boundary. They are different. Tool bundle lifetimes belong to the caller: dispose on close and on failed `createAgent`. LSP is a plugin passed as `{ ...env, plugins: [lsp(env)] }`. A tool can return a `pendingMarker` to open a correlation gate. |
| 80 | + |
| 81 | +## Inference |
| 82 | + |
| 83 | +- List several `sources` for failover across providers and protocols. `agent.setSource()` hot-swaps without interrupting a call. |
| 84 | +- Extra providers (OpenAI Responses, Codex, xAI, Ollama) come from Corbits packages: `use_skill corbits-inference`. |
| 85 | +- Oversize tool output spills to a blob with a `tool-output://` URI (`sizeCapMaxChars`). |
| 86 | + |
| 87 | +## Test |
| 88 | + |
| 89 | +Use `@intx/inference-testing` for scripted replies and to swap `fetch`. Assert on tool_result content, not just absence of crashes. |
| 90 | + |
| 91 | +## Examples to copy (upstream `examples/`) |
| 92 | + |
| 93 | +`agent-quickstart` (start here), `coding-agent` (posix plus LSP), `agent-resume`, `agent-rewind`, `agent-audit-log`, `agent-blob-spill`, `agent-rich-tool`, `agent-structured-payload`, `agent-multi-provider`, `agent-gemini-image`, `posix-demo` and `ring-demo` (multi-agent mail). Run with `bun --conditions=intx-src run src/cli.ts`. |
| 94 | + |
| 95 | +## Need more |
| 96 | + |
| 97 | +- Reactor, directors, compaction, failover: upstream `docs/INFERENCE.md`. |
| 98 | +- Durable multi-step work: `use_skill interchange-workflows`. |
| 99 | +- Running it somewhere other than your process: `use_skill interchange-run-modes`. |
| 100 | +- Back to the overview: `use_skill interchange`. |
0 commit comments