POST /api/agents/companionAgent/generate

Generate a complete response from the companion agent without streaming.

Request Body

Array

required

Conversation history array containing user and assistant messages.

string

default:"friend"

Personality mode for the response. Options: "guru", "wanderer", "friend", "philosopher"

string

Unique identifier for the conversation thread. Recommended for conversation continuity.

string

User identifier for conversation persistence. Recommended for user-specific conversations.

string

Alternative personality specification method.

Request Example

{
  "messages": [
    {
      "role": "user",
      "content": "What is the weather like in Tokyo?"
    }
  ],
  "runtimeContext": {
    "metadata": {
      "personality": "friend",
      "userId": "user123"
    }
  },
  "threadId": "thread-abc123",
  "resourceId": "user-123"
}

Response

string

The complete response text from the companion agent.

object

Token usage statistics for the request.

number

Number of input tokens used.

number

Number of output tokens generated.

number

Total tokens used (input + output).

number

Tokens used for reasoning (if applicable).

number

Cached input tokens (cost savings).

Array

Detailed execution steps including tool calls and results.

string

Reason for response completion ("stop", "length", "tool_calls", etc.)

Array

Any warnings generated during processing.

object

Provider-specific metadata (OpenAI, etc.)

string

Unique request trace identifier for debugging.

Success Response (200)

{
  "text": "The weather in Tokyo is currently 22°C with partly cloudy conditions. It feels like 25°C with moderate humidity. This seems like pleasant weather for a meditation session in one of the city's beautiful temples!",
  "usage": {
    "inputTokens": 15,
    "outputTokens": 45,
    "totalTokens": 60,
    "reasoningTokens": 0,
    "cachedInputTokens": 0
  },
  "steps": [
    {
      "stepType": "initial",
      "sources": [],
      "files": [],
      "toolCalls": [
        {
          "toolCallId": "call_weather_123",
          "toolName": "weatherTool",
          "args": {
            "location": "Tokyo"
          }
        }
      ],
      "toolResults": [
        {
          "toolCallId": "call_weather_123",
          "toolName": "weatherTool",
          "result": {
            "temperature": 22,
            "feelsLike": 25,
            "humidity": 65,
            "windSpeed": 5,
            "windGust": 8,
            "conditions": "Partly cloudy",
            "location": "Tokyo"
          }
        }
      ],
      "content": [
        {
          "type": "text",
          "text": "The weather in Tokyo is currently 22°C with partly cloudy conditions..."
        }
      ],
      "text": "The weather in Tokyo is currently 22°C with partly cloudy conditions...",
      "reasoningText": "",
      "reasoning": [],
      "staticToolCalls": [],
      "dynamicToolCalls": [
        {
          "toolCallId": "call_weather_123",
          "toolName": "weatherTool",
          "args": {
            "location": "Tokyo"
          },
          "providerMetadata": {}
        }
      ],
      "staticToolResults": [],
      "dynamicToolResults": [
        {
          "toolCallId": "call_weather_123",
          "toolName": "weatherTool",
          "result": {
            "temperature": 22,
            "feelsLike": 25,
            "humidity": 65,
            "windSpeed": 5,
            "windGust": 8,
            "conditions": "Partly cloudy",
            "location": "Tokyo"
          }
        }
      ],
      "finishReason": "stop",
      "usage": {
        "inputTokens": 15,
        "outputTokens": 45,
        "totalTokens": 60,
        "reasoningTokens": 0,
        "cachedInputTokens": 0
      },
      "warnings": [],
      "request": {
        "body": {}
      },
      "response": {
        "id": "resp_123",
        "timestamp": "2025-11-21T10:30:00.000Z",
        "modelId": "openai/gpt-4o-mini",
        "headers": {},
        "modelMetadata": {},
        "messages": [],
        "uiMessages": [
          {
            "id": "msg_123",
            "role": "assistant",
            "metadata": {
              "createdAt": "2025-11-21T10:30:00.000Z",
              "threadId": "thread-abc123",
              "resourceId": "user-123"
            },
            "parts": [
              {
                "type": "text",
                "text": "The weather in Tokyo is currently 22°C with partly cloudy conditions..."
              }
            ]
          }
        ]
      },
      "providerMetadata": {},
      "totalUsage": {
        "inputTokens": 15,
        "outputTokens": 45,
        "totalTokens": 60,
        "reasoningTokens": 0,
        "cachedInputTokens": 0
      },
      "tripwire": false,
      "tripwireReason": "",
      "traceId": "trace-abc123"
    }
  ],
  "finishReason": "stop",
  "warnings": [],
  "providerMetadata": {},
  "request": {
    "body": {}
  },
  "reasoning": [],
  "toolCalls": [
    {
      "toolCallId": "call_weather_123",
      "toolName": "weatherTool",
      "args": {
        "location": "Tokyo"
      },
      "providerMetadata": {}
    }
  ],
  "toolResults": [
    {
      "toolCallId": "call_weather_123",
      "toolName": "weatherTool",
      "result": {
        "temperature": 22,
        "feelsLike": 25,
        "humidity": 65,
        "windSpeed": 5,
        "windGust": 8,
        "conditions": "Partly cloudy",
        "location": "Tokyo"
      }
    }
  ],
  "sources": [],
  "files": [],
  "response": {},
  "totalUsage": {
    "inputTokens": 15,
    "outputTokens": 45,
    "totalTokens": 60,
    "reasoningTokens": 0,
    "cachedInputTokens": 0
  },
  "tripwire": false,
  "tripwireReason": "",
  "traceId": "trace-abc123"
}

Error Responses

Code	Description
400	Invalid request body or parameters
500	Server-side processing error

cURL Example

curl -X POST https://oyester.metaphy.live/api/agents/companionAgent/generate \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Hello! What can you help me with today?"
      }
    ],
    "runtimeContext": {
      "metadata": {
        "personality": "friend"
      }
    },
    "threadId": "demo-thread-001",
    "resourceId": "demo-user"
  }'

Getting Started

Core API

Tools

Personalities

Reference

Generate Response

POST /api/agents/companionAgent/generate

Request Body

Request Example

Response

Success Response (200)

Error Responses

cURL Example

​POST /api/agents/companionAgent/generate

​Request Body

​Request Example

​Response

​Success Response (200)

​Error Responses

​cURL Example

POST /api/agents/companionAgent/generate

Request Body

Request Example

Response

Success Response (200)

Error Responses

cURL Example