Getting started with Agents

An agent is a reusable configuration for answering prompts: a set of instructions, the knowledge it can draw on, and the tools it can use. Once created, you run an agent by passing its agent_id to Converse. This guide walks through creating an agent, configuring it, and running it. For the full field reference, see the Agents API reference.

Before you begin

Make sure you have an API key and an SDK installed. See the Quickstart if you haven’t set those up yet.

Create your first agent

Every field on POST /agents is optional, so the smallest useful agent is just a name and some instructions.

import os
from datagrid_ai import Datagrid

client = Datagrid(api_key=os.environ.get("DATAGRID_API_KEY"))

agent = client.agents.create(
    name="Support Assistant",
    system_prompt="You are a helpful support assistant. Answer concisely and cite sources.",
)

print(agent.id)

import Datagrid from 'datagrid-ai';

const client = new Datagrid({ apiKey: process.env['DATAGRID_API_KEY'] });

const agent = await client.agents.create({
  name: 'Support Assistant',
  system_prompt: 'You are a helpful support assistant. Answer concisely and cite sources.',
});

console.log(agent.id);

The response is an Agent object. Keep its id — you’ll pass it to Converse to run the agent.

Configure instructions

Agents have three instruction fields, each with a distinct purpose:

Field	Use it for
`system_prompt`	The agent’s role, scope, and behavior — what it should do.
`custom_prompt`	Style and formatting preferences — how responses should look.
`planning_prompt`	How the agent should break down and approach complex, multi-step tasks.

agent = client.agents.create(
    name="Support Assistant",
    system_prompt="You are a support assistant for a construction software company.",
    custom_prompt="Respond in short paragraphs. Use bullet points for steps.",
)

const agent = await client.agents.create({
  name: 'Support Assistant',
  system_prompt: 'You are a support assistant for a construction software company.',
  custom_prompt: 'Respond in short paragraphs. Use bullet points for steps.',
});

Add knowledge with `corpus`

By default an agent can use all knowledge your organization or teamspace can access. To scope it to specific sources, pass a corpus array. Each item is either a knowledge base or a page.

agent = client.agents.create(
    name="Policy Assistant",
    system_prompt="Answer questions about company policy.",
    corpus=[
        {"type": "knowledge", "knowledge_id": "kn_abc123"},
        {"type": "page", "page_id": "page_xyz789"},
    ],
)

const agent = await client.agents.create({
  name: 'Policy Assistant',
  system_prompt: 'Answer questions about company policy.',
  corpus: [
    { type: 'knowledge', knowledge_id: 'kn_abc123' },
    { type: 'page', page_id: 'page_xyz789' },
  ],
});

For predictable behavior and to avoid exposing more knowledge than intended, set corpus explicitly instead of relying on the all-knowledge default. See Knowledge and corpus for details.

Enable tools

Tools let an agent do more than answer from knowledge — search the web, analyze data, extract from documents, and more. Pass a tools array of tool names. If you omit tools, a default set is used; passing [] disables all tools.

agent = client.agents.create(
    name="Research Assistant",
    system_prompt="Research topics and summarize findings.",
    tools=["semantic_search", "web_search", "data_analysis"],
)

const agent = await client.agents.create({
  name: 'Research Assistant',
  system_prompt: 'Research topics and summarize findings.',
  tools: ['semantic_search', 'web_search', 'data_analysis'],
});

To see every available tool, use the List tools endpoint. You can also pass disabled_tools to remove specific tools from the default set.

Generate an agent from natural language

Instead of authoring fields by hand, you can describe the agent you want and get a suggested configuration back. This is a three-step flow:

Generate a template from a prompt (POST /agents/generate).
Claim the template with the returned token to retrieve its config (POST /agents/claim).
Create the agent from the template fields (POST /agents).

agents.generate returns a claim_token that expires after 7 days. Claiming retrieves the template — it does not create the agent, so you still call agents.create to persist it.

# 1. Generate a template
generated = client.agents.generate(
    prompt="An agent that reviews RFIs and flags missing information.",
)

# 2. Claim the template to retrieve its configuration
template = client.agents.claim(claim_token=generated.claim_token)

# 3. Create the agent from the template
agent = client.agents.create(
    name=template.title,
    system_prompt=template.config.prompt,
    custom_prompt=template.config.custom_prompt,
    tools=[t.tool for t in template.config.tools],
)

print(agent.id)

// 1. Generate a template
const generated = await client.agents.generate({
  prompt: 'An agent that reviews RFIs and flags missing information.',
});

// 2. Claim the template to retrieve its configuration
const template = await client.agents.claim({ claim_token: generated.claim_token });

// 3. Create the agent from the template
const agent = await client.agents.create({
  name: template.title,
  system_prompt: template.config.prompt,
  custom_prompt: template.config.custom_prompt,
  tools: template.config.tools.map((t) => t.tool),
});

console.log(agent.id);

The generate response lists tools as { "tool": "<name>" } objects, while agents.create expects tool names (strings). Map them as shown above (t.tool / t => t.tool).

Run your agent

Pass the agent’s id as agent_id on a Converse call. The agent’s stored instructions, corpus, and tools are applied automatically.

response = client.converse(
    prompt="What's our policy on remote work?",
    agent_id=agent.id,
)

print(response.content[0].text)

const response = await client.converse({
  prompt: "What's our policy on remote work?",
  agent_id: agent.id,
});

console.log(response.content[0].text);

You can override any part of the agent’s configuration for a single turn by passing config on the Converse call — this does not change the stored agent.

response = client.converse(
    prompt="Summarize only the Q4 policy updates.",
    agent_id=agent.id,
    config={"corpus": [{"type": "knowledge", "knowledge_id": "kn_q4_policies"}]},
)

const response = await client.converse({
  prompt: 'Summarize only the Q4 policy updates.',
  agent_id: agent.id,
  config: { corpus: [{ type: 'knowledge', knowledge_id: 'kn_q4_policies' }] },
});

Update and delete

Update an agent with the same fields you used to create it (a partial update — only the fields you pass change):

client.agents.update(agent.id, system_prompt="You are a concise, friendly assistant.")

await client.agents.update(agent.id, {
  system_prompt: 'You are a concise, friendly assistant.',
});

Delete an agent when you no longer need it:

client.agents.delete(agent.id)

await client.agents.delete(agent.id);

Next steps

Getting started with Converse — the endpoint you use to run agents.
Knowledge and corpus — scope what your agent can read.
Agents API reference — every field and endpoint.

⌘I

Introduction

Converse

Voice

Identity

Agents

Automations

Knowledge

Search

Conversations

Messages

Connections

Connection Providers

Connectors

Files

Tools

Secrets

Webhooks

Memory

Pages

MCP Servers - Beta

Batch Predictions

Event Triggers

Organization

Getting started with Agents

Before you begin

Create your first agent

Configure instructions

Add knowledge with `corpus`

Enable tools

Generate an agent from natural language

Run your agent

Update and delete

Next steps

​Before you begin

​Create your first agent

​Configure instructions

​Add knowledge with corpus

​Enable tools

​Generate an agent from natural language

​Run your agent

​Update and delete

​Next steps

Before you begin

Create your first agent

Configure instructions

Add knowledge with `corpus`

Enable tools

Generate an agent from natural language

Run your agent

Update and delete

Next steps