Build your first agent¶

At the end of this tutorial you have an agent support that answers customers' questions, and your application calls it with only its name and the question. You have also made a second version and seen how an application stays on one version.

The examples in the tutorials follow one case: you are a partner building a support assistant for your customer Noordwind, a trading company. In this tutorial you build the agent in your own organisation.

1. Check what your key may do¶

curl -s "$CORE_URL/key" -H "Authorization: Bearer $CORE_KEY"

The answer (abridged) must list agents under capabilities:

{
  "id": "key_7Hn2...",
  "tenant_id": "ten_4Kd9...",
  "capabilities": { "agents": {} }
}

You look first because a missing capability later looks like a path that does not exist: the routes under /agents then answer 404.

2. Choose a model¶

curl -s "$CORE_URL/models" -H "Authorization: Bearer $CORE_KEY"

The list data holds the chat models your key may call. Take the id of one of them; the examples write <a model id>.

Which models exist differs per installation and per key. Taking a model id from this list keeps you from storing an agent on a model your key cannot reach.

3. Store the agent¶

curl -s -X POST "$CORE_URL/agents" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"name": "support",
         "description": "Answers questions from customers about orders and returns.",
         "model": "<a model id>",
         "instructions": "You are the support assistant of Noordwind. Answer briefly. If you are not sure of something, say so.",
         "temperature": 0.2}'

The answer is 201 with the agent and its first version (abridged):

{
  "id": "agt_5Nj2...",
  "object": "agent",
  "name": "support",
  "latest_version": {
    "version": 1,
    "model": "<a model id>",
    "instructions": "You are the support assistant of Noordwind. ...",
    "temperature": 0.2
  }
}

Keep the id for the next steps:

export AGENT_ID=agt_5Nj2...

Only name is required. You store the model, the instruction and the temperature here because you want to change them later without rolling out your application again. Choose the name with care: your application and a key's policy refer to it.

In the console you do the same under Agents.

4. Call the agent¶

curl -s -X POST "$CORE_URL/responses" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"agent": {"id": "support"},
         "input": "Can I still change an order after I have paid?"}'

The answer has the same shape as for a request without an agent (abridged):

{
  "id": "resp_0KQ2mR...",
  "status": "completed",
  "model": "<a model id>",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "That depends on ..." }]
    }
  ]
}

The request names no model and no instruction: they come from the agent. Your application only needs to know the name support.

5. Make a second version¶

You want the agent to always end with a question. That is a new version:

curl -s -X POST "$CORE_URL/agents/$AGENT_ID/versions" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"model": "<a model id>",
         "instructions": "You are the support assistant of Noordwind. Answer briefly. If you are not sure of something, say so. End by asking whether you can help with anything else.",
         "temperature": 0.2}'

A version is the whole definition. What you do not send again is not in the new version, which is why the model and the temperature are there again. Versions do not change after they are created, so you can always find out what ran at a given moment.

A request without a version number uses version 2 from now on. The call from step 4 does not have to change.

6. Pin your application to a version¶

curl -s -X POST "$CORE_URL/responses" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"agent": {"id": "support", "version": 1},
         "input": "Can I still change an order after I have paid?"}'

With version a request stays on that version, also after new ones are made. Use that in production when you want to try a new version first: your test environment leaves version out, your production environment names the number you approved.

Check that it works¶

Three things show the agent does what you stored:

1. The call from step 4 now ends with a question, and the one from step 6 does not. Both versions exist side by side.
2. GET /agents/$AGENT_ID/versions returns two versions.

3. A request that tries to override a stored field is refused:

   curl -s -X POST "$CORE_URL/responses" \
       -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
       -d '{"agent": {"id": "support"}, "temperature": 0.9, "input": "Hello"}'
   

   This answers 400 with temperature in error.param. That is how you know, for every turn, which definition ran.

If it does not work¶

The full list is in Agents through the API.

Read on¶

• Agents: what an agent stores and when you use one.
• Agents through the API: every field, and what a request may add.
• Prompts through the API: a template with variables that an agent pins.
• Make a model call: the fields of a request, and streaming.

Next tutorial: Give an agent knowledge from your own business information.