Frequently Asked Questions
Answers to common questions about Agent Connect
This page provides answers to common questions about Agent Connect and the Agent Connect Framework.
General Questions
What is Agent Connect Framework?
Agent Connect Framework (ACF) is a comprehensive framework that provides specifications, APIs, and tools for developers to seamlessly integrate AI agents with IBM watsonx Orchestrate. It enables agents built with any framework to collaborate with other agents in the watsonx ecosystem, unlocking powerful multi-agent workflows and capabilities.
How is ACF different from other agent frameworks?
ACF is not an agent framework itself, but rather a specification for how agents can communicate and collaborate. It’s designed to work with existing agent frameworks like LangChain, LangGraph, CrewAI, and others. The key difference is that ACF focuses on standardizing the communication between agents, rather than how agents are built internally.
Do I need to use IBM watsonx to use ACF?
While ACF is designed to work seamlessly with IBM watsonx Orchestrate, you can implement the ACF API endpoints in any agent and have it communicate with other agents that also implement these endpoints. However, to take full advantage of the enterprise features like governance, security, and scalability, integration with watsonx Orchestrate is recommended.
Is ACF open source?
The ACF specification is openly documented and can be implemented by anyone. Some reference implementations and tools may be provided as open source, while others may be part of IBM’s commercial offerings.
What’s the difference between ACF and Agent Connect?
The Agent Connect Framework is a foundational integration architecture designed to enable seamless connectivity between external agents and watsonx Orchestrate.
IBM Agent Connect, on the other hand, is a partner program that offers independent software vendors (ISVs) the opportunity to collaborate with IBM. The program extends the technical benefits of the framework by fostering strategic partnerships that drive business value and innovation within the watsonx Orchestrate environment.
Technical Questions
What endpoints do I need to implement to be compatible with ACF?
At a minimum, you need to implement:
- GET /v1/agents: The agent discovery endpoint that provides information about your agent
- POST /v1/chat: The chat completion endpoint that allows other agents to communicate with your agent
Does my agent need to support streaming responses?
While not strictly required, it is highly recommended that your agent supports streaming responses using Server-Sent Events (SSE). This provides a better user experience and allows other agents to see intermediate steps in your agent’s reasoning process, which can be valuable for collaboration.
How do I handle stateful conversations?
Agent Connect supports stateful conversations through the use of thread IDs. When a client sends a request to your agent, it may include an X-THREAD-ID header. Your agent should store any relevant conversation state keyed by this thread ID, and retrieve it when subsequent requests arrive with the same thread ID.
Can my agent use tools from other agents?
Yes, ACF supports tool calling between agents. Your agent can expose tools that other agents can call, and it can also call tools exposed by other agents. This is done through the standardized tool calling format in the chat completion API.
How do I handle authentication and security?
Authentication and security are typically handled at the watsonx Orchestrate level. When you register your agent with Orchestrate, you can configure authentication requirements. For direct agent-to-agent communication outside of Orchestrate, you would need to implement your own authentication mechanisms.
Implementation Questions
What programming languages can I use to implement ACF?
You can implement ACF in any programming language that can serve HTTP endpoints. The examples in our documentation use Python with FastAPI, but you could use Node.js, Java, Go, or any other language of your choice.
How do I test my ACF implementation?
You can test your implementation by:
- Using tools like Postman or curl to send requests to your endpoints
- Using the watsonx Orchestrate test tools when registering your agent
- Creating a simple client that implements the ACF client protocol
How do I deploy my ACF-compatible agent?
You can deploy your agent on any platform that can host web services, such as:
- Cloud platforms (AWS, Azure, Google Cloud)
- Container orchestration systems (Redhat OpenShift, Kubernetes, Docker Swarm)
- Serverless platforms (AWS Lambda, Google Cloud Functions)
- Traditional web servers
The only requirement is that your agent must be accessible via HTTPS from watsonx Orchestrate or other agents that need to communicate with it.
How do I handle errors and rate limiting?
Your agent should return appropriate HTTP status codes for different error conditions:
- 400 Bad Request: For invalid input
- 401 Unauthorized: For authentication failures
- 429 Too Many Requests: For rate limiting
- 500 Internal Server Error: For server-side errors
Include descriptive error messages in the response body to help clients understand what went wrong.
Integration with watsonx Orchestrate
How do I register my agent with watsonx Orchestrate?
To register your agent with watsonx Orchestrate:
- Log in to the watsonx Orchestrate dashboard
- Navigate to the Agent Management section
- Click “Add External Agent”
- Provide your agent’s URL and other required information
- Test the connection
- Save and activate your agent
What information does watsonx Orchestrate need about my agent?
watsonx Orchestrate needs:
- Your agent’s base URL
- A name and description for your agent
- Information about your agent’s capabilities (e.g., streaming support)
- Any authentication requirements
Can I update my agent after it’s registered?
Yes, you can update your agent’s implementation at any time. As long as you maintain the same API endpoints and functionality, watsonx Orchestrate will continue to work with your updated agent. If you need to make breaking changes, you may need to register a new version of your agent.
How does billing work for IBM Agent Connect?
Billing depends on your specific agreement with IBM. Generally, there may be costs associated with:
- Usage of watsonx Orchestrate
- API calls to and from your agent
- Usage of IBM AI models through the AI Gateway
Contact your IBM representative for specific billing information.
Troubleshooting
My agent isn’t being discovered by watsonx Orchestrate
Check that:
- Your agent’s chat endpoint (e.g.
POST /v1/chat) is accessible - The endpoint returns a valid response in the expected format
- Your agent’s URL is correctly configured in watsonx Orchestrate
- There are no network issues preventing communication (make sure your endpoint is routable over the network)
My agent receives requests but watsonx Orchestrate doesn’t receive responses
Check that:
- Your agent’s chat completion endpoint (e.g.
POST /v1/chat) is correctly implemented - The endpoint returns responses in the expected format
- If using streaming, ensure your SSE implementation is correct
- Check for any timeouts or connection issues
Tool calls aren’t working correctly
Check that:
- Your tool call format matches the expected format
- Tool responses are correctly formatted
- Tools are properly registered and documented
- Your agent has permission to call your tools
My agent is slow to respond
Consider:
- Optimizing your agent’s implementation
- Using streaming to provide partial responses quickly
- Implementing caching for common requests
- Scaling your agent’s infrastructure
Getting Help
If you can’t find the answer to your question here, you can:
- Check the documentation for more detailed information
- Contact IBM Support for assistance
- Join the community forums to ask questions and share experiences