# Structured Output

> Get typed JSON responses from your agent using outputschema.

**URL:** https://inference.sh/docs/api/agent/structured-output
**Last updated:** 2026-10-31

---

Get typed JSON responses from your agent using `output_schema`.

---

## How It Works

When you set `output_schema` on an agent config, the agent's **finish tool** is configured to require output matching your schema. Instead of free-form text, the agent returns structured JSON.

1. You define a JSON Schema in `output_schema`
2. The finish tool's parameters are set to your schema
3. The agent calls `finish` with data matching the schema
4. You get predictable, parseable output

Requires `internal_tools.finish` to be enabled (on by default). Setting `output_schema` is what offers `finish` to a top-level agent; sub-agents always get it. Calling `finish` ends the run. See [Internal Tools — Finish](/docs/api/agent/internal-tools#finish-tool).

---

## Basic Example

<div data-type="codegroup">

```python Python
from inferencesh import inference

client = inference(api_key="inf_...")

agent = client.agent({
    "core_app": { "ref": "infsh/claude-sonnet-4@latest" },
    "system_prompt": "Analyze the sentiment of the given text.",
    "output_schema": {
        "type": "object",
        "properties": {
            "sentiment": {
                "type": "string",
                "enum": ["positive", "negative", "neutral"],
                "description": "Overall sentiment"
            },
            "confidence": {
                "type": "number",
                "description": "Confidence score between 0 and 1"
            },
            "summary": {
                "type": "string",
                "description": "One-sentence summary"
            }
        },
        "required": ["sentiment", "confidence", "summary"]
    },
    "internal_tools": { "finish": True }
})

output = agent.run("This product exceeded all my expectations!")
# output = {"sentiment": "positive", "confidence": 0.95, "summary": "..."}
```

```typescript JavaScript
import { inference } from '@inferencesh/sdk';

const client = inference({ apiKey: 'inf_...' });

const agent = client.agent({
  core_app: { ref: 'infsh/claude-sonnet-4@latest' },
  system_prompt: 'Analyze the sentiment of the given text.',
  output_schema: {
    type: 'object',
    properties: {
      sentiment: {
        type: 'string',
        enum: ['positive', 'negative', 'neutral'],
        description: 'Overall sentiment'
      },
      confidence: {
        type: 'number',
        description: 'Confidence score between 0 and 1'
      },
      summary: {
        type: 'string',
        description: 'One-sentence summary'
      }
    },
    required: ['sentiment', 'confidence', 'summary']
  },
  internal_tools: { finish: true }
});

const output = await agent.run('This product exceeded all my expectations!');
// output = {"sentiment": "positive", "confidence": 0.95, "summary": "..."}
```

</div>

---

## Reading the Output

The simplest way to get structured output is `agent.run()` — it sends the message, waits for the agent to finish, and returns `chat.output` directly:

<div data-type="codegroup">

```python Python
output = agent.run("This product exceeded all my expectations!")
print(output)
# {"sentiment": "positive", "confidence": 0.95, "summary": "Very positive product review"}
```

```typescript JavaScript
const output = await agent.run('This product exceeded all my expectations!');
console.log(output);
// {"sentiment": "positive", "confidence": 0.95, "summary": "Very positive product review"}
```

</div>

If you need more control, use `sendMessage` + `getChat` separately:

<div data-type="codegroup">

```python Python
response = agent.send_message("This product exceeded all my expectations!")
chat = agent.get_chat()
print(chat.get("output"))
```

```typescript JavaScript
const response = await agent.sendMessage('This product exceeded all my expectations!');
const chat = await agent.getChat();
console.log(chat.output);
```

</div>

In the React provider, access it via the chat state:

```tsx
const { chat } = useAgentChat();

if (chat?.output) {
  console.log(chat.output); // structured finish output
}
```

### REST API

After the agent finishes, `GET /chats/:id` includes an `output` field with the same structured payload as the SDK. Poll this endpoint if you are not using the Agent SDK.

→ [Get Chat](/docs/api/rest/agents#get-chat)

### OpenAI-compatible agent route

If you call the agent through the OpenAI dialect (`POST /agents/{namespace}/{name}/openai/chat/completions`), `choices[0].message.content` is the agent's last assistant message text for the turn — the same Chat Completions semantics as other providers — not the validated JSON from `finish`. Read `chat.output` with `agent.run()`, run streaming, or `GET /chats/:id` after the run completes.

→ [OpenAI-Compatible API — Agents](/docs/api/rest/openai#agents)

---

## Using Schema Helpers

You can use the SDK's built-in schema helpers instead of writing raw JSON Schema:

<div data-type="codegroup">

```python Python
from inferencesh import obj, string, number, array, enum_of, optional

schema = obj({
    "sentiment": enum_of(["positive", "negative", "neutral"], "Overall sentiment"),
    "confidence": number("Confidence score 0-1"),
    "summary": string("One-sentence summary"),
    "keywords": array(string(), "Extracted keywords"),
    "language": optional(string("Detected language")),
})

agent = client.agent({
    "core_app": { "ref": "infsh/claude-sonnet-4@latest" },
    "output_schema": schema,
    "internal_tools": { "finish": True }
})
```

```typescript JavaScript
import { object, string, number, array, enumOf, optional } from '@inferencesh/sdk';

const schema = object({
  sentiment: enumOf(['positive', 'negative', 'neutral'], 'Overall sentiment'),
  confidence: number('Confidence score 0-1'),
  summary: string('One-sentence summary'),
  keywords: array(string(), 'Extracted keywords'),
  language: optional(string('Detected language')),
});

const agent = client.agent({
  core_app: { ref: 'infsh/claude-sonnet-4@latest' },
  output_schema: schema,
  internal_tools: { finish: true }
});
```

</div>

---

## Schema Format

`output_schema` accepts standard [JSON Schema](https://json-schema.org/) objects:

```json
{
  "type": "object",
  "properties": {
    "field_name": {
      "type": "string",
      "description": "What this field contains"
    }
  },
  "required": ["field_name"]
}
```

Supported types: `string`, `number`, `integer`, `boolean`, `array`, `object`

Use `enum` for constrained values:
```json
{ "type": "string", "enum": ["option_a", "option_b"] }
```

Use `description` on every field — it helps the LLM understand what to put there.

---

## Use Cases

### Data Extraction

```python
agent = client.agent({
    "core_app": { "ref": "infsh/claude-sonnet-4@latest" },
    "system_prompt": "Extract contact information from the given text.",
    "output_schema": {
        "type": "object",
        "properties": {
            "name": { "type": "string" },
            "email": { "type": "string" },
            "phone": { "type": "string" },
            "company": { "type": "string" }
        },
        "required": ["name"]
    },
    "internal_tools": { "finish": True }
})
```

### Classification

```python
agent = client.agent({
    "core_app": { "ref": "infsh/claude-sonnet-4@latest" },
    "system_prompt": "Classify the support ticket.",
    "output_schema": {
        "type": "object",
        "properties": {
            "category": {
                "type": "string",
                "enum": ["billing", "technical", "account", "other"]
            },
            "priority": {
                "type": "string",
                "enum": ["low", "medium", "high", "urgent"]
            },
            "suggested_action": { "type": "string" }
        },
        "required": ["category", "priority"]
    },
    "internal_tools": { "finish": True }
})
```

### Multi-step Analysis with Tools

Structured output works alongside other tools. The agent can use tools to gather information, then return structured results:

```python
from inferencesh import tool, string, app_tool

search = (
    tool("search_docs")
    .describe("Search internal documentation")
    .param("query", string("Search query"))
    .handler(lambda args: search_index(args["query"]))
)

agent = client.agent({
    "core_app": { "ref": "infsh/claude-sonnet-4@latest" },
    "system_prompt": "Research the topic using available tools, then summarize findings.",
    "tools": [search],
    "output_schema": {
        "type": "object",
        "properties": {
            "findings": {
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {
                        "title": { "type": "string" },
                        "relevance": { "type": "number" },
                        "summary": { "type": "string" }
                    }
                }
            },
            "recommendation": { "type": "string" }
        },
        "required": ["findings", "recommendation"]
    },
    "internal_tools": { "finish": True }
})
```

---

## Tips

- **Always include `required`** — without it, the agent may omit fields
- **Use `description` on every property** — it acts as instructions for the LLM
- **Use `enum` for categorical data** — constrains output to valid values
- **Keep schemas focused** — one clear purpose per agent, not a kitchen sink
- **Set a clear `system_prompt`** — tell the agent what to do, the schema tells it how to format the result
