Skip to main content

​
POST /api/agents/companionAgent/generate

Generate a complete response from the companion agent without streaming.

​
Request Body

​
messages
Array
required
Conversation history array containing user and assistant messages.
​
runtimeContext.metadata.personality
string
default:"friend"
Personality mode for the response. Options: "guru", "wanderer", "friend", "philosopher"
​
threadId
string
Unique identifier for the conversation thread. Recommended for conversation continuity.
​
resourceId
string
User identifier for conversation persistence. Recommended for user-specific conversations.
​
tracingOptions.metadata.personality
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

​
text
string
The complete response text from the companion agent.
​
usage
object
Token usage statistics for the request.
​
usage.inputTokens
number
Number of input tokens used.
​
usage.outputTokens
number
Number of output tokens generated.
​
usage.totalTokens
number
Total tokens used (input + output).
​
usage.reasoningTokens
number
Tokens used for reasoning (if applicable).
​
usage.cachedInputTokens
number
Cached input tokens (cost savings).
​
steps
Array
Detailed execution steps including tool calls and results.
​
finishReason
string
Reason for response completion ("stop", "length", "tool_calls", etc.)
​
warnings
Array
Any warnings generated during processing.
​
providerMetadata
object
Provider-specific metadata (OpenAI, etc.)
​
traceId
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

CodeDescription
400Invalid request body or parameters
500Server-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"
  }'