Skip to main content

Hosted agents

Save a prompt and retrieval configuration once, then invoke it on demand — buffered or streaming.

Create a saved agent#

Persist a system prompt + tool configuration you can invoke by slug.

Agents bundle a system prompt, default model, and collection scopes behind a stable slug your code can invoke. The SDKs only support invoking saved agents — creation is a REST call. After creation, refer to the agent by `slug` everywhere.

// POST /orgs/:orgId/projects/:projectId/agents
const res = await fetch(
  `https://api.meetdewey.com/v1/orgs/${orgId}/projects/${projectId}/agents`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.DEWEY_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      slug: 'qa-test',
      name: 'QA copilot',
      systemPrompt: 'You answer questions about our quarterly reports.',
      defaultModel: 'gpt-5',
      collectionIds: ['COLLECTION_ID'],
    }),
  },
)
const agent = await res.json()
console.log(agent.slug, '→', agent.id)

See also

Invoke an agent (buffered)#

Run a saved agent and get the full response back at once.

Uses the agent's saved system prompt, default model, and collection scopes. Pass the `orgId`, `projectId`, and `agentSlug` — these are visible in the dashboard URL for the agent. The CLI caches org and project IDs after `dewey config set`.

dewey agents invoke qa-test "What did we say about indemnification?"

Response

{
  "runId": "run_xyz",
  "status": "completed",
  "response": "The contracts specify mutual indemnification with a cap of...",
  "iterationsUsed": 4,
  "sources": [
    {
      "chunkId": "chk_8a",
      "sectionTitle": "Indemnification",
      "documentId": "doc_a1",
      "filename": "msa.pdf"
    }
  ]
}

See also

Invoke an agent (streaming)#

Stream tokens, tool calls, and tool results from a saved agent.

Yields five event types: `run_started`, `tool_call` (the agent invoked retrieval), `tool_result` (the tool came back), `chunk` (a token of the answer), `done` (final response + sources). Use it to drive a chat UI with live tool-trace.

# Streaming is the default when stdout is a TTY.
dewey agents invoke qa-test "summarize Q3 vs Q2 revenue" --stream

See also

Preview without saving#

Try a system prompt + tool config without creating an agent.

Preview is a one-shot streaming call that takes the same payload as `create` but doesn't persist anything. Useful when iterating on a system prompt or model choice from a settings page. Only available via REST today.

// POST /orgs/:orgId/projects/:projectId/agents/:slug/preview
// The :slug here is a free-form identifier you choose for the preview run.
const res = await fetch(
  `https://api.meetdewey.com/v1/orgs/${orgId}/projects/${projectId}/agents/draft/preview`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.DEWEY_API_KEY}`,
      'Content-Type': 'application/json',
      Accept: 'text/event-stream',
    },
    body: JSON.stringify({
      query: 'summarize Q3 vs Q2 revenue',
      systemPrompt: 'You answer questions about our quarterly reports.',
      defaultModel: 'gpt-5',
      collectionIds: ['COLLECTION_ID'],
    }),
  },
)

// Consume `res.body` as an SSE stream.

List run history#

Inspect prior agent runs from the dashboard.

Every agent invocation is recorded as a run with its query, sources, and iteration trace. Run history is currently surfaced through the dashboard's Runs tab — there isn't a public REST endpoint yet. Point users at the dashboard URL for an agent and they can replay any past run.

See also