Core concepts

A handful of nouns carry the whole platform: project, agent, smith, thread, run. Everything else (tools, memory, deployments, billing) hangs off one of them.

The one distinction to get right first is agent vs. smith — they sound alike and aren't. An agent is the design of an assistant; a smith is one running clone of that design, one per end-user of your product. It's the same split as a class and its instances, or a recipe and each plate you serve. You write one agent; Ingram Cloud runs a private smith of it for every user, each with its own memory, conversations, and connections. That one-to-many shape is what makes this more than a chatbot builder: not one bot, but one design and N isolated assistants — one per person.

The hierarchy at a glance

Organization        your company account (teammates + sign-in)
  └─ Project        an isolated tenant, switch in the sidebar
       ├─ Agent     the design of an assistant, defined once, versioned
       └─ Smith     one per end-user, runs a clone of an agent
            ├─ Thread   a conversation
            │    └─ Run   one turn
            └─ Memory    facts the smith keeps about this person

An agent is the reusable design: instructions, model, enabled tools, auto-memory. A smith is one of your end-users: their personal running clone of an agent, holding their own memory, threads, and connections. You publish an agent and roll it out; every smith pointed at it runs that design, with optional per-smith pins or overrides.

Your identity lives in your API token, never in a URL. The token says which project (tenant) and, optionally, which smith you are, so you never pass an id to choose "whose data".

Projects are the hard tenant boundary

A project is an isolated silo: its own smiths, agents, tools, connections, memory, tokens, and usage. The project id is the tenant that scopes every query: data never crosses between projects, and a token minted in one project is cryptographically incapable of reading another. Use separate projects for separate environments (staging vs production) or separate products. Switch or create them from the project picker at the top of the sidebar (the New project action opens a name prompt); delete one from Settings → Project. Teammates and invites live under Settings → Team.

Smiths: one per end-user of your product

A smith is one of your end-users, created from your backend (POST /v1/smiths) with external_id mapping to your own user id. The smith owns everything personal: memory, conversation threads, OAuth connections, deployments, schedules. Because memory is per smith, one person's facts can never surface in another person's conversation. That isolation is the point of creating one smith per person rather than sharing one.

Logged-out visitors are smiths too — keyed to a random token under an anon: namespace instead of your user id. When to give someone a new smith versus just a new thread, how teams map onto customers, and the anonymous-to-login flow are all in Modeling your users.

Threads and runs

A thread is a conversation. Pass a stable thread_id across a person's turns and the smith keeps history; omit it and each turn starts fresh.

A run is one turn: input in, events out, output recorded. Runs can pause (for a tool you execute, or for a human approval) and resume when you submit the result via /submit. Details on Runs & streaming.

Agents: define behaviour once

When all your smiths should run the same assistant, design it once as an agent and point smiths at it by reference. Publishing creates immutable versions; rollouts move every attached smith at once (staged by percentage if you want); individual smiths can pin a version or carry small overrides. See Agents.

A smith always runs a clone of an agent: the one it's attached to, or your project's default agent if it names none, so it's never agent-less. The config a smith actually runs with is its effective config, resolved at request time.

Managing it in the console

• Smiths and Agents (Build): create, configure, attach, roll out.
• Runs / Approvals / Events (Observe): what happened, what's waiting.
• Usage & cost (Spend) vs Customers (Revenue): what you pay vs what you bill; the two never share a page.
• Settings: split into organization-wide settings (Organization for projects, Team for teammates, Billing) and the active project's settings (Integrations for Slack/Telegram/email, Models for provider keys, API Keys for tenant tokens).