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": 123,
  "presence_penalty": 123,
  "logit_bias": {},
  "logprobs": true,
  "top_logprobs": 123,
  "max_tokens": 123,
  "max_completion_tokens": 123,
  "temperature": 123,
  "n": 123,
  "seed": 123,
  "stop": [
    "<string>"
  ],
  "stream": true,
  "top_p": 123,
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "<string>",
        "description": "<string>",
        "parameters": {}
      }
    }
  ],
  "tool_choice": "<string>",
  "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': None, 'city': None, 'country': 'India', 'dateOfBirth': datetime.date(1998, 6, 30), 'defaultFullName': 'Vijaya Singh', 'department': 'HR Total Rewards (5000145)', 'email': 'kota.manaswini@partner.ibm.com', 'firstName': 'Vijaya', 'gender': ' ', 'hireDate': datetime.date(2023, 6, 30), 'lastName': 'Singh', 'salary': None, 'state': None, 'title': 'Digital Consultant', 'userId': '103451', 'businessPhone': None, '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

Response

200
application/json

Successful Response

The response is of type object.