> ## Documentation Index
> Fetch the complete documentation index at: https://developers.datagrid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting started with Agents

> Create, configure, and run AI agents with the Datagrid API.

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](/api-reference/converse/converse).

This guide walks through creating an agent, configuring it, and running it. For the full field reference, see the [Agents API reference](/api-reference/agents/create-agent).

## Before you begin

Make sure you have an API key and an SDK installed. See the [Quickstart](/introduction/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.

<CodeGroup>
  ```python Python theme={null}
  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)
  ```

  ```javascript JavaScript theme={null}
  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);
  ```
</CodeGroup>

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. |

<CodeGroup>
  ```python Python theme={null}
  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.",
  )
  ```

  ```javascript JavaScript theme={null}
  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.',
  });
  ```
</CodeGroup>

## 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.

<CodeGroup>
  ```python Python theme={null}
  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"},
      ],
  )
  ```

  ```javascript JavaScript theme={null}
  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' },
    ],
  });
  ```
</CodeGroup>

<Tip>
  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](/api-reference/converse/knowledge-and-corpus) for details.
</Tip>

## 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.

<CodeGroup>
  ```python Python theme={null}
  agent = client.agents.create(
      name="Research Assistant",
      system_prompt="Research topics and summarize findings.",
      tools=["semantic_search", "web_search", "data_analysis"],
  )
  ```

  ```javascript JavaScript theme={null}
  const agent = await client.agents.create({
    name: 'Research Assistant',
    system_prompt: 'Research topics and summarize findings.',
    tools: ['semantic_search', 'web_search', 'data_analysis'],
  });
  ```
</CodeGroup>

To see every available tool, use the [List tools](/api-reference/tools/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:

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

<Note>
  `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.
</Note>

<CodeGroup>
  ```python Python theme={null}
  # 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)
  ```

  ```javascript JavaScript theme={null}
  // 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);
  ```
</CodeGroup>

<Note>
  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`).
</Note>

## 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.

<CodeGroup>
  ```python Python theme={null}
  response = client.converse(
      prompt="What's our policy on remote work?",
      agent_id=agent.id,
  )

  print(response.content[0].text)
  ```

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

  console.log(response.content[0].text);
  ```
</CodeGroup>

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.

<CodeGroup>
  ```python Python theme={null}
  response = client.converse(
      prompt="Summarize only the Q4 policy updates.",
      agent_id=agent.id,
      config={"corpus": [{"type": "knowledge", "knowledge_id": "kn_q4_policies"}]},
  )
  ```

  ```javascript JavaScript theme={null}
  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' }] },
  });
  ```
</CodeGroup>

## Update and delete

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

<CodeGroup>
  ```python Python theme={null}
  client.agents.update(agent.id, system_prompt="You are a concise, friendly assistant.")
  ```

  ```javascript JavaScript theme={null}
  await client.agents.update(agent.id, {
    system_prompt: 'You are a concise, friendly assistant.',
  });
  ```
</CodeGroup>

Delete an agent when you no longer need it:

<CodeGroup>
  ```python Python theme={null}
  client.agents.delete(agent.id)
  ```

  ```javascript JavaScript theme={null}
  await client.agents.delete(agent.id);
  ```
</CodeGroup>

## Next steps

* [Getting started with Converse](/api-reference/converse/converse-getting-started) — the endpoint you use to run agents.
* [Knowledge and corpus](/api-reference/converse/knowledge-and-corpus) — scope what your agent can read.
* [Agents API reference](/api-reference/agents/create-agent) — every field and endpoint.