> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oyester.metaphy.live/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate Response

> Generate a non-streaming response from the companion agent

# POST /api/agents/companionAgent/generate

Generate a complete response from the companion agent without streaming.

## Request Body

<ParamField body="messages" type="Array" required>
  Conversation history array containing user and assistant messages.
</ParamField>

<ParamField body="runtimeContext.metadata.personality" type="string" default="friend">
  Personality mode for the response. Options: `"guru"`, `"wanderer"`, `"friend"`, `"philosopher"`
</ParamField>

<ParamField body="threadId" type="string">
  Unique identifier for the conversation thread. Recommended for conversation continuity.
</ParamField>

<ParamField body="resourceId" type="string">
  User identifier for conversation persistence. Recommended for user-specific conversations.
</ParamField>

<ParamField body="tracingOptions.metadata.personality" type="string">
  Alternative personality specification method.
</ParamField>

## Request Example

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

## Response

<ResponseField name="text" type="string">
  The complete response text from the companion agent.
</ResponseField>

<ResponseField name="usage" type="object">
  Token usage statistics for the request.
</ResponseField>

<ResponseField name="usage.inputTokens" type="number">
  Number of input tokens used.
</ResponseField>

<ResponseField name="usage.outputTokens" type="number">
  Number of output tokens generated.
</ResponseField>

<ResponseField name="usage.totalTokens" type="number">
  Total tokens used (input + output).
</ResponseField>

<ResponseField name="usage.reasoningTokens" type="number">
  Tokens used for reasoning (if applicable).
</ResponseField>

<ResponseField name="usage.cachedInputTokens" type="number">
  Cached input tokens (cost savings).
</ResponseField>

<ResponseField name="steps" type="Array">
  Detailed execution steps including tool calls and results.
</ResponseField>

<ResponseField name="finishReason" type="string">
  Reason for response completion (`"stop"`, `"length"`, `"tool_calls"`, etc.)
</ResponseField>

<ResponseField name="warnings" type="Array">
  Any warnings generated during processing.
</ResponseField>

<ResponseField name="providerMetadata" type="object">
  Provider-specific metadata (OpenAI, etc.)
</ResponseField>

<ResponseField name="traceId" type="string">
  Unique request trace identifier for debugging.
</ResponseField>

## Success Response (200)

```json theme={null}
{
  "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

```bash theme={null}
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"
  }'
```