Agent Interaction

Create and interact with AI agents using the Python client

Agents are AI assistants that can search your knowledge base and answer questions.

Create Agent Settings

# Create agent configuration
agent_settings = warehouse.create_agent_settings({
    "name": "Invoice Assistant",
    "instructions": "You are a helpful assistant that answers questions about invoices.",
    "model": "gpt-4o",
    "temperature": 0.7,
    "tool_ids": ["tool-id-1", "tool-id-2"]  # Tools this agent can use
})

print(f"Created agent settings: {agent_settings['id']}")

Get a Playground Agent

# Get an agent instance
agent = warehouse.get_playground_agent(agent_settings_id="agent-settings-id")

print(f"Agent: {agent.agent_settings_id}")

Create a Conversation and Send Messages

# Create a new conversation
conversation = agent.create_conversation(
    conversation_instructions="Be concise and focus on financial details"
)

print(f"Created conversation: {conversation['id']}")

# Send a message
answer = agent.send_message(
    conversation_id=conversation['id'],
    message_text="What invoices do we have from Acme Corp?"
)

print(f"Agent response: {answer}")

One-Shot Conversation

For simple queries, create a conversation and send a message in one call:

# Create conversation and send message
result = agent.create_conversation_and_send_message(
    message_text="What are the total outstanding invoices?",
    conversation_instructions="Provide amounts in USD",
    file_paths=["/path/to/additional-doc.pdf"]  # Optional: upload files
)

print(f"Question: {result['query']}")
print(f"Answer: {result['answer']}")
print(f"Conversation ID: {result['conversation_id']}")

Upload Files to a Conversation

# Upload local files to an existing conversation
documents = agent.upload_local_documents_to_conversation(
    conversation_id="conv-id",
    file_paths=[
        "/path/to/file1.pdf",
        "/path/to/file2.pdf"
    ],
    batch_size=10
)

# Then send a message referencing the uploaded files
answer = agent.send_message(
    conversation_id="conv-id",
    message_text="Summarize the uploaded documents"
)

Get Conversation History

# Get full conversation history
history = agent.get_conversation_history(conversation_id="conv-id")

for message in history:
    role = message.get('role')
    content = message.get('content')
    print(f"{role}: {content}")

List Agent Conversations

# List all conversations for this agent
conversations = agent.list_conversations()
for conv in conversations:
    print(f"Conversation: {conv['name']} (ID: {conv['id']})")
    print(f"  Created: {conv['created_at']}")

Delete a Conversation

# Delete a conversation
warehouse.delete_conversation(conversation_id="conv-id")

Upload Local Documents to Agent Settings

Upload documents specific to an agent configuration that will be available to all conversations using that agent:

# Upload local documents to agent settings
documents = warehouse.upload_local_documents_to_agent_settings(
    agent_settings_id="agent-settings-id",
    file_paths=["/path/to/doc1.pdf", "/path/to/doc2.pdf"],
    batch_size=10
)

# These documents will be available to all conversations using this agent
print(f"Uploaded {len(documents)} documents to agent settings")

# List local documents for agent settings
docs = warehouse.list_local_documents_for_agent_settings(
    agent_settings_id="agent-settings-id"
)

for doc in docs:
    print(f"Document: {doc['file_name']} (ID: {doc['id']})")

# Delete a local document from agent settings
warehouse.delete_local_document_from_agent_settings(
    agent_settings_id="agent-settings-id",
    local_document_id="doc-id"
)