Octagon

Appearance

Responses API ​

IMPORTANT

Streaming is required for all Octagon agents. Non-streaming requests are not supported.

The Responses API is the newest and recommended 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:

bash
pip install openai
bash
npm install openai

Request Parameters ​

ParameterTypeRequiredDescription
modelstringYesThe ID of the agent model to use. See Available Agents.
instructionsstringNoBehavioral instructions for the agent to follow.
inputstringYesThe user's input/query.
streambooleanYesMust be set to true for all agent requests.

Basic Usage Example ​

Python
from openai import OpenAI

client = OpenAI(
    api_key="your-octagon-api-key",
    base_url="https://api.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.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.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

Handling Citations in Responses ​

Octagon agents provide citations to sources. These will appear in the completed response:

Python
from openai import OpenAI

client = OpenAI(
    api_key="your-octagon-api-key",
    base_url="https://api.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.octagonagents.com/v1'
});

async function getAnalysisWithCitations() {
  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}`);
        });
      }
    }
  }
}

getAnalysisWithCitations();
cURL
# With cURL you'll need to parse the stream events manually
# This example shows the API request - parsing would need to be done with additional tools

curl -X POST https://api.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

# The response will be a stream of events
# You'll need to identify "response.output_text.delta" events for text content
# And "response.completed" events to extract citations

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 ​