Skip to main content
POST
/
v1
/
chat
Create Chat Completion
curl --request POST \
  --url https://your-agent-server.com/agent-connect/v1/chat \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "<string>",
  "messages": [
    {}
  ],
  "frequency_penalty": 0,
  "presence_penalty": 0,
  "logit_bias": {},
  "logprobs": true,
  "top_logprobs": 123,
  "max_tokens": 123,
  "max_completion_tokens": 123,
  "temperature": 1,
  "n": 1,
  "seed": 123,
  "stop": [
    "<string>"
  ],
  "stream": false,
  "top_p": 1,
  "tools": [
    {
      "function": {
        "name": "<string>",
        "description": "<string>",
        "parameters": {}
      },
      "type": "function"
    }
  ],
  "tool_choice": "auto",
  "parallel_tool_calls": true,
  "user": "<string>",
  "metadata": {},
  "extra_body": {}
}
'
{
  "id": "<string>",
  "object": "<string>",
  "created": 123,
  "model": "<string>",
  "choices": [
    {
      "index": 123,
      "message": {
        "role": "user",
        "content": "<string>"
      },
      "finish_reason": "<string>"
    }
  ]
}
Agents must implement this endpoint.
The Chat API enables agents to communicate and collaborate with each other using a standard chat completions style protocol with server-sent events (SSE) for streaming responses. This API supports both stateful and stateless agents.

​
Stateful interactions

For stateful interactions, agents can use the provided X-THREAD-ID header to correlate requests to long-running message threads. This allows agents to maintain context and provide more accurate responses. IBM watsonx Orchestrate can track the full message history across agents, including tool calls and tool responses provided that agents participate by emitting tool calls and tool responses in their response event stream.

​
Stateless interactions

For stateless interactions, it is assumed that the sender will include a set of messages relevant to the current conversation thread with the user. Agents should be cautious not to reveal sensitive information.

​
Streaming responses

It is highly recommended that agents implement the streaming version of this operation. This option provides the best user experience and allows the calling agent to have visibility into the intermediate steps of the agents it is collaborating with. The following example illustrates an event stream that relays internal tool call details back to the calling agent: 
[
  {
    "event": "thread.run.step.delta",
    "data": {
      "id": "step-a0844e",
      "object": "thread.run.step.delta",
      "thread_id": "t-01",
      "model": "agent-1",
      "created": 1728566532,
      "choices": [
        {
          "delta": {
            "role": "assistant",
            "step_details": {
              "type": "tool_calls",
              "tool_calls": [
                {
                  "id": "e32ff32a4",
                  "name": "find_employee_by_name",
                  "args": {
                    "name": "Vijaya S"
                  }
                }
              ]
            }
          }
        }
      ]
    }
  },
  {
    "event": "thread.run.step.delta",
    "data": {
      "id": "step-03050c",
      "object": "thread.run.step.delta",
      "thread_id": "t-01",
      "model": "agent-1",
      "created": 1729091694,
      "choices": [
        {
          "delta": {
            "role": "assistant",
            "step_details": {
              "type": "tool_response",
              "content": "[{\"cellPhone\": null, \"city\": null, \"country\": \"India\", \"dateOfBirth\": \"1998-06-30\", \"defaultFullName\": \"Vijaya Singh\", \"department\": \"HR Total Rewards (5000145)\", \"email\": \"[email protected]\", \"firstName\": \"Vijaya\", \"gender\": \" \", \"hireDate\": \"2023-06-30\", \"lastName\": \"Singh\", \"salary\": null, \"state\": null, \"title\": \"Digital Consultant\", \"userId\": \"103451\", \"businessPhone\": null, \"location\": \"Hyderabad (6200-0005)\"}]",
              "name": "find_employee_by_name",
              "tool_call_id": "e32ff32a4"
            }
          }
        }
      ]
    }
  }
]
By relaying the internal tool call details back to the calling agent, downstream steps (other agents or tool calls) can take advantage of the information discovered by this agent enhancing the collaboration potential in a multi-agent scenario.
Implementers of this operation have discretion to determine which tool calls, if any, to relay back to the calling agent. However, it is crucial to exercise caution when sharing internal tool call details to prevent exposing sensitive information. Agents should establish and adhere to clear guidelines for filtering or redacting sensitive content from shared tool call data to maintain confidentiality and ensure compliance with relevant data protection regulations.

​
Thinking steps

Agents can also stream intermediate “thinking” steps to provide a glimpse into the steps they are taking while working on a task. For example: 
{
  "event": "thread.run.step.delta",
  "data": {
    "id": "step-d08460",
    "object": "thread.run.step.delta",
    "thread_id": "t01",
    "model": "agent-1",
    "created": 1728566531,
    "choices": [
      {
        "delta": {
          "role": "assistant",
          "step_details": {
            "type": "thinking",
            "content": "The agent's response is a generic greeting and does not address the user's specific question about upcoming holidays in the US. I should use the available tools to find the relevant information and provide a more specific and helpful response."
          }
        }
      }
    ]
  }
}

{
  "id": "<string>",
  "object": "<string>",
  "created": 123,
  "model": "<string>",
  "choices": [
    {
      "index": 123,
      "message": {
        "role": "user",
        "content": "<string>"
      },
      "finish_reason": "<string>"
    }
  ]
}

Body

application/json
​
model
string
required
​
messages
Messages · object[]
required
​
frequency_penalty
number | null
default:0
​
presence_penalty
number | null
default:0
​
logit_bias
Logit Bias · object
​
logprobs
boolean | null
​
top_logprobs
integer | null
​
max_tokens
integer | null
​
max_completion_tokens
integer | null
​
temperature
number | null
default:1
​
n
integer | null
default:1
​
seed
integer | null
​
stop
string[] | null
​
stream
boolean | null
default:false
​
top_p
number | null
default:1
​
tools
Tool · object[] | null
​
tool_choice
string | null
default:auto
​
parallel_tool_calls
boolean | null
default:true
​
user
string | null
​
metadata
Metadata · object
​
extra_body
Extra Body · object

Response

Successful Response

​
id
string
required
​
created
integer
required
​
model
string
required
​
choices
Choice · object[]
required
​
usage
Usage · object
required
​
object
string
default:chat.completion
Allowed value: "chat.completion"
​
system_fingerprint
string | null
​
extra_body
Extra Body · object