Responses API

The Responses API is the newest way to integrate with Octagon. It offers improved event streaming, additional context through events, and better support for tool use with parallel tool calls.

Overview of the Responses API

Responses is a more flexible and powerful API than Chat Completions, designed to support more complex interactions and workflows. It offers:

1. Structured event streaming: Events clearly indicate when responses start, are in progress, and complete
2. Rich output types: Support for text, images, and tool calls in a structured format
3. Parallel tool calls: Efficient execution of multiple tool calls simultaneously
4. Enhanced metadata: More detailed information about the response, including token usage

Installation

Install the OpenAI SDK:

Python

pip install openai

JavaScript

npm install openai

Request Parameters

Parameter	Type	Required	Description
model	string	Yes	The ID of the agent model to use. See Available Agents.
instructions	string	No	Behavioral instructions for the agent to follow.
input	string	Yes	The user's input/query.
stream	boolean	No	When set to true, enables event streaming of the response.

Basic Usage Example

Python

from openai import OpenAI

client = OpenAI(
    # Note: Replace with your API key or use environment variables
    api_key="your-octagon-api-key",
    base_url="https://api-gateway.octagonagents.com/v1"
)

# Make the API call using the responses endpoint
response = client.responses.create(
    model="octagon-sec-agent",
    instructions="You analyze SEC filings and extract financial data.",
    input="What were Apple's revenue numbers in Q3 2023?"
)

# Extract and print the analysis text
analysis_text = response.output[0].content[0].text
print("ANALYSIS:")
print(analysis_text)

# Extract and print citations
annotations = response.output[0].content[0].annotations
print("\nSOURCES:")
for annotation in annotations:
    print(f"{annotation.order}. {annotation.name}: {annotation.url}")

# Example output:

# ANALYSIS:
# In the third quarter of 2023, Apple's total net sales were $81,797 million. This included $60,584 million from products and $21,213 million from services [1], [2].

# SOURCES:
# 1. Apple Inc. (10-Q) - 2023-Q3, Page: 10: https://octagon-sec-filings.s3.amazonaws.com/320193/0000320193-23-000077/aapl-20230701.pdf?response-content-disposition=inline&response-content-type=application%2Fpdf&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAYGEZZN2EGRGVN56Y%2F20250401%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20250401T220525Z&X-Amz-Expires=604800&X-Amz-SignedHeaders=host&X-Amz-Signature=783c748f003e66bbdb61b2da4b49e3a31da0213617ff2237d1316da2885ca515#page=10
# 2. Apple Inc. (10-Q) - 2023-Q3, Page: 4: https://octagon-sec-filings.s3.amazonaws.com/320193/0000320193-23-000077/aapl-20230701.pdf?response-content-disposition=inline&response-content-type=application%2Fpdf&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAYGEZZN2EGRGVN56Y%2F20250401%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20250401T220525Z&X-Amz-Expires=604800&X-Amz-SignedHeaders=host&X-Amz-Signature=783c748f003e66bbdb61b2da4b49e3a31da0213617ff2237d1316da2885ca515#page=4

JavaScript

import OpenAI from 'openai';

const client = new OpenAI({
  // Note: Replace with your API key or use environment variables
  apiKey: 'your-octagon-api-key',
  baseURL: 'https://api-gateway.octagonagents.com/v1'
});

async function getAnalysis() {
  // Make the API call using the responses endpoint
  const response = await client.responses.create({
    model: "octagon-sec-agent",
    instructions: "You analyze SEC filings and extract financial data.",
    input: "What were Apple's revenue numbers in Q3 2023?"
  });

  // Extract and print the analysis text
  const analysisText = response.output[0].content[0].text;
  console.log("ANALYSIS:");
  console.log(analysisText);

  // Extract and print citations
  const annotations = response.output[0].content[0].annotations;
  console.log("\nSOURCES:");
  annotations.forEach(annotation => {
    console.log(`${annotation.order}. ${annotation.name}: ${annotation.url}`);
  });
}

getAnalysis();

// Example output:

// ANALYSIS:
// In the third quarter of 2023, Apple's total net sales were $81,797 million. This included $60,584 million from products and $21,213 million from services [1], [2].

// SOURCES:
// 1. Apple Inc. (10-Q) - 2023-Q3, Page: 10: https://octagon-sec-filings.s3.amazonaws.com/320193/0000320193-23-000077/aapl-20230701.pdf?response-content-disposition=inline&response-content-type=application%2Fpdf&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAYGEZZN2EGRGVN56Y%2F20250401%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20250401T220525Z&X-Amz-Expires=604800&X-Amz-SignedHeaders=host&X-Amz-Signature=783c748f003e66bbdb61b2da4b49e3a31da0213617ff2237d1316da2885ca515#page=10
// 2. Apple Inc. (10-Q) - 2023-Q3, Page: 4: https://octagon-sec-filings.s3.amazonaws.com/320193/0000320193-23-000077/aapl-20230701.pdf?response-content-disposition=inline&response-content-type=application%2Fpdf&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAYGEZZN2EGRGVN56Y%2F20250401%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20250401T220525Z&X-Amz-Expires=604800&X-Amz-SignedHeaders=host&X-Amz-Signature=783c748f003e66bbdb61b2da4b49e3a31da0213617ff2237d1316da2885ca515#page=4

cURL

curl -X POST https://api-gateway.octagonagents.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-octagon-api-key" \
  -d '{
    "model": "octagon-sec-agent",
    "instructions": "You analyze SEC filings and extract financial data.",
    "input": "What were Apple'\''s revenue numbers in Q3 2023?"
  }'

Streaming Example

Python

from openai import OpenAI

client = OpenAI(
    api_key="your-octagon-api-key",
    base_url="https://api-gateway.octagonagents.com/v1"
)

response = client.responses.create(
    model="octagon-sec-agent",
    instructions="You analyze SEC filings and extract financial data.",
    input="What were Apple's revenue numbers in Q3 2023?",
    stream=True
)

full_analysis = ""
citations = []

for event in response:
    # Extract text from delta events
    if event.type == "response.output_text.delta":
        full_analysis += event.delta
        print(event.delta, end="")
    
    # Extract citations from the completed event
    if event.type == "response.completed":
        if hasattr(event.response, "citations"):
            citations = event.response.citations
            
            print("\n\nSOURCES:")
            for citation in citations:
                print(f"{citation.order}. {citation.name}: {citation.url}")

JavaScript

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'your-octagon-api-key',
  baseURL: 'https://api-gateway.octagonagents.com/v1'
});

async function getAnalysis() {
  const response = await client.responses.create({
    model: "octagon-sec-agent",
    instructions: "You analyze SEC filings and extract financial data.",
    input: "What were Apple'\''s revenue numbers in Q3 2023?",
    stream: true
  });

  let fullAnalysis = "";
  let citations = [];

  for await (const event of response) {
    // Extract text from delta events
    if (event.type === "response.output_text.delta") {
      fullAnalysis += event.delta;
      process.stdout.write(event.delta);
    }
    
    // Extract citations from the completed event
    if (event.type === "response.completed") {
      if (event.response.citations) {
        citations = event.response.citations;
        
        console.log("\n\nSOURCES:");
        citations.forEach(citation => {
          console.log(`${citation.order}. ${citation.name}: ${citation.url}`);
        });
      }
    }
  }
}

getAnalysis();

cURL

curl -X POST https://api-gateway.octagonagents.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-octagon-api-key" \
  -d '{
    "model": "octagon-sec-agent",
    "instructions": "You analyze SEC filings and extract financial data.",
    "input": "What were Apple'\''s revenue numbers in Q3 2023?",
    "stream": true
  }' \
  --no-buffer

# Note: Handling the stream response with cURL requires additional
# processing to extract the deltas and citations

Understanding Response Event Types

When using the Responses API with streaming, you'll receive a series of events:

• response.created: The initial event indicating the response has been created
• response.in_progress: Indicates that the response is being generated
• response.output_item.added: A new output item (message, image, etc.) is being added
• response.content_part.added: A new content part within an output item is being added
• response.output_text.delta: New text is being added to the response
• response.output_text.done: The text part of the response is complete
• response.content_part.done: A content part is complete
• response.output_item.done: An output item is complete
• response.completed: The entire response is complete

Best Practices

1. Use Clear Instructions: Set clear and specific instructions for the agent to provide better context.
2. Process Event Types Appropriately: Handle different event types properly to create a responsive UI.
3. Handle Citations: Display citations when available to provide sources for the information.
4. Implement Error Handling: Have robust error handling for network disruptions during streaming.

Next Steps

• View available agent models → for detailed capabilities
• Learn about authentication → for secure access
• Try the Chat Completions API → for a simpler interface