🆘 AMCP Support & Resources

Find help, troubleshoot issues, and learn how to build amazing agentic systems with AMCP.

Table of Contents

  1. Getting Help
  2. Documentation
  3. Troubleshooting
  4. Common Issues
  5. Performance Tips
  6. Security & Best Practices
  7. Community Resources

Getting Help

Need Resource Time
Getting Started First Agent Tutorial 5 min
API Reference API Documentation 10 min
Examples Example Applications 15 min
Troubleshooting Troubleshooting Guide 10 min
Ask Questions GitHub Discussions 24 hours
Report Bugs GitHub Issues 48 hours

Support Channels

📚 Documentation     → https://agentmeshcommunicationprotocol.github.io/docs/
💬 Discussions       → https://github.com/agentmeshcommunicationprotocol/amcpcore/discussions
🐛 Bug Reports       → https://github.com/agentmeshcommunicationprotocol/amcpcore/issues
📧 Email Support     → support@amcp.dev
🐦 Twitter           → @amcp_framework
💻 Stack Overflow    → tag: amcp

Documentation

Core Documentation

Getting Started

Guides & Tutorials

Reference

Migration & Upgrade

Example Applications

📦 Weather Agent       → /examples/weather-agent/
📦 Stock Agent         → /examples/stock-agent/
📦 Travel Agent        → /examples/travel-agent/
📦 More Examples       → /examples/

Troubleshooting

Common Problems & Solutions

1. Build Issues

Problem: Maven build fails

# Solution 1: Clean build
mvn clean install

# Solution 2: Update dependencies
mvn dependency:resolve

# Solution 3: Check Java version
java -version  # Should be 11+

# Solution 4: Clear Maven cache
rm -rf ~/.m2/repository
mvn clean install

2. Startup Issues

Problem: Agent fails to start

# Check logs
quarkus dev

# Common causes:
# - Port already in use
# - Kafka not running
# - LLM endpoint not available
# - Configuration error

# Solutions:
# Use different port
quarkus dev -Dquarkus.http.port=8081

# Start Kafka
docker run -d --name kafka -p 9092:9092 confluentinc/cp-kafka:latest

# Disable LLM if not needed
# In application.properties:
# amcp.llm.enabled=false

3. Kafka Connection Issues

Problem: Cannot connect to Kafka

# Check Kafka is running
docker ps | grep kafka

# Check bootstrap servers
# In application.properties:
kafka.bootstrap.servers=localhost:9092

# Test connection
kafka-broker-api-versions --bootstrap-server localhost:9092

# If using Docker:
docker run -d --name kafka \
  -p 9092:9092 \
  confluentinc/cp-kafka:latest

4. LLM Connection Issues

Problem: Cannot connect to LLM endpoint

# Check endpoint is running
curl http://localhost:8000/health

# Verify configuration
# In application.properties:
amcp.llm.provider=local
amcp.llm.local.endpoint=http://localhost:8000

# Test with curl
curl -X POST http://localhost:8000/chat \
  -d '{"message": "Hello"}'

# If using OpenAI:
# Check API key is set
echo $OPENAI_API_KEY

# If using local LLM:
# Start Ollama or similar
ollama serve

5. Memory Issues

Problem: Out of memory errors

# Increase heap size
export JAVA_OPTS="-Xmx512m"
quarkus dev

# Or in Maven
mvn quarkus:dev -Dquarkus.jvm.java-opts="-Xmx512m"

# Check memory usage
jps -l
jmap -heap <pid>

6. Performance Issues

Problem: Slow response times

# Enable debug logging
# In application.properties:
quarkus.log.level=DEBUG

# Check latency
# Use performance monitoring tools
# Review Best Practices guide

# Common causes:
# - LLM latency (1000ms+)
# - Kafka latency
# - Network issues
# - Resource constraints

Common Issues

Issue 1: “Port 8080 already in use”

Error:

Address already in use: bind

Solution:

# Option 1: Use different port
quarkus dev -Dquarkus.http.port=8081

# Option 2: Kill process using port
lsof -i :8080
kill -9 <PID>

# Option 3: Check what's using the port
netstat -tlnp | grep 8080

Issue 2: “Cannot find Kafka broker”

Error:

org.apache.kafka.common.errors.TimeoutException

Solution:

# Start Kafka
docker run -d --name kafka \
  -p 9092:9092 \
  confluentinc/cp-kafka:latest

# Or verify it's running
docker ps | grep kafka

# Check bootstrap servers in config
# kafka.bootstrap.servers=localhost:9092

Issue 3: “LLM API key not found”

Error:

OpenAI API key not configured

Solution:

# Set environment variable
export OPENAI_API_KEY="your-key-here"

# Or in application.properties
amcp.llm.openai.api-key=your-key-here

# Or use system property
-Damcp.llm.openai.api-key=your-key-here

Issue 4: “Agent initialization failed”

Error:

AgentContext not found

Solution:

// Ensure initialize method has context parameter
@Override
public void initialize(AgentContext context) {  // ✅ Correct
    context.subscribe("topic", this::handleMessage);
}

// Not like this:
@Override
public void initialize() {  // ❌ Wrong
    this.subscribe("topic", this::handleMessage);
}

Issue 5: “Tests failing”

Error:

Test failed: Expected X but got Y

Solution:

# Run tests with verbose output
mvn test -X

# Run specific test
mvn test -Dtest=MyAgentTest

# Run with coverage
mvn test jacoco:report

# Check test logs
cat target/surefire-reports/

Performance Tips

1. Optimize LLM Calls

// ✅ Good: Cache responses
@Cacheable(value = "llm-responses")
public String chat(String message) {
    return llmService.chat(message, config);
}

// ✅ Good: Use prompt caching
ChatConfig config = new ChatConfig()
    .cachePrompt(true)
    .temperature(0.7);

// ❌ Avoid: Repeated calls for same input
for (int i = 0; i < 100; i++) {
    llmService.chat("same message", config);  // Wasteful
}

2. Optimize Kafka Usage

// ✅ Good: Batch messages
List<String> batch = new ArrayList<>();
for (Message msg : messages) {
    batch.add(msg.getPayload());
    if (batch.size() >= 100) {
        producer.sendBatch(topic, batch);
        batch.clear();
    }
}

// ✅ Good: Use async sending
producer.sendAsync(topic, message, callback);

// ❌ Avoid: Synchronous calls in loop
for (Message msg : messages) {
    producer.send(topic, msg);  // Blocks on each send
}

3. Optimize Memory

// ✅ Good: Use object pooling
ObjectPool<Message> pool = new ObjectPool<>(Message::new);
Message msg = pool.acquire();
// Use message
pool.release(msg);

// ✅ Good: Stream large datasets
Stream<Message> messages = getMessages();
messages.forEach(this::process);

// ❌ Avoid: Loading all in memory
List<Message> all = getMessages().collect(toList());  // OOM risk

4. Optimize Queries

// ✅ Good: Use filtering
agents.stream()
    .filter(a -> a.getStatus() == ACTIVE)
    .map(Agent::getName)
    .collect(toList());

// ✅ Good: Use pagination
List<Agent> page = agents.stream()
    .skip((pageNum - 1) * pageSize)
    .limit(pageSize)
    .collect(toList());

// ❌ Avoid: Processing all data
agents.stream()
    .map(Agent::getName)
    .collect(toList());  // Processes everything

5. Optimize Logging

// ✅ Good: Use appropriate levels
logger.debug("Processing message: {}", message);  // Debug level
logger.info("Agent started: {}", agentName);      // Info level
logger.warn("Retry attempt {}", attempt);         // Warning level
logger.error("Error occurred", exception);        // Error level

// ✅ Good: Use lazy evaluation
logger.debug("Details: {}", () -> expensiveOperation());

// ❌ Avoid: String concatenation
logger.debug("Processing: " + message);  // Always evaluated

Security & Best Practices

Security Checklist

Security Configuration

# Enable mTLS
amcp.security.mtls.enabled=true
amcp.security.mtls.cert-path=/path/to/cert.pem
amcp.security.mtls.key-path=/path/to/key.pem

# Enable RBAC
amcp.security.rbac.enabled=true

# Enable audit logging
amcp.security.audit.enabled=true
amcp.security.audit.log-path=/var/log/amcp/audit.log

# Use secrets
amcp.llm.openai.api-key=${OPENAI_API_KEY}

Best Practices

  1. Never hardcode secrets 
    // ❌ Bad
String apiKey = "sk-1234567890";
   
// ✅ Good
String apiKey = System.getenv("OPENAI_API_KEY");
  2. Validate all inputs 
    // ✅ Good
if (message == null || message.isEmpty()) {
    throw new IllegalArgumentException("Message cannot be empty");
}
  3. Use HTTPS 
    quarkus.http.ssl.certificate.files=/path/to/cert.pem
quarkus.http.ssl.certificate.key-files=/path/to/key.pem
  4. Implement rate limiting 
    @RateLimit(requests = 100, period = 1, unit = TimeUnit.MINUTES)
public void handleRequest() { }
  5. Keep dependencies updated 
    mvn dependency:update-properties
mvn versions:use-latest-versions

Community Resources

Learning Resources

External Resources

Community Help

Getting More Help

Still Need Help?

  1. Check Documentation: /docs/
  2. Search Discussions: GitHub Discussions
  3. Ask a Question: New Discussion
  4. Report a Bug: New Issue
  5. Contact Support: support@amcp.dev

Feedback

Help Us Improve

We’re constantly improving AMCP. Help us by:

Thank You!

Thank you for using AMCP! We’re here to help you build amazing agentic systems.

Need help? We’re here for you! 🚀

Support Email: support@amcp.dev
Documentation: /docs/
GitHub: Issues | Discussions