CtrlK

Community Documentation Log in Get started

tessl/maven-com-embabel-agent--embabel-agent-a2a

A2A protocol integration for Embabel Agent Framework enabling agent-to-agent communication

Overview

Eval results

Files

Troubleshooting

Name: tessl/maven-com-embabel-agent--embabel-agent-a2a
Author: tessl

Solutions to common issues.

Endpoints Not Registered

Symptoms: 404 errors when accessing /a2a/.well-known/agent.json or /a2a

Check Logs:

INFO  c.e.a.a.s.A2AEndpointRegistrar - Registering 1 A2A endpoints
INFO  c.e.a.a.s.A2AEndpointRegistrar - Registering web endpoint under /a2a/.well-known/agent.json

Solution 1: Ensure component scanning includes A2A packages

@SpringBootApplication
@ComponentScan(basePackages = [
    "com.embabel.agent.a2a",
    "your.application.package"
])
class Application

Solution 2: Verify AgentCardHandler bean exists

@Autowired
lateinit var agentCardHandler: AgentCardHandler  // Should inject successfully

No AgentCardHandler Bean Created

Symptoms: Bean injection fails with "No qualifying bean of type 'AgentCardHandler'"

Solution: Check A2AConfiguration is being scanned. Explicitly import if needed:

@SpringBootApplication
@Import(A2AConfiguration::class)
class Application

Multiple Handlers with Same Path

Symptoms: Only one handler responds, or unexpected behavior

Solution: Ensure each AgentCardHandler has unique path:

@Bean
fun handler1(...): AgentCardHandler =
    EmbabelServerGoalsAgentCardHandler(path = "a2a-public", ...)

@Bean
fun handler2(...): AgentCardHandler =
    EmbabelServerGoalsAgentCardHandler(path = "a2a-partner", ...)

Missing Embabel Framework Dependencies

Symptoms:

NoClassDefFoundError: com/embabel/agent/core/AgentPlatform
NoClassDefFoundError: com/embabel/agent/api/Autonomy

Solution: Add required Embabel dependencies:

<dependency>
    <groupId>com.embabel.agent</groupId>
    <artifactId>embabel-agent-core</artifactId>
    <version>VERSION</version>
</dependency>
<dependency>
    <groupId>com.embabel.agent</groupId>
    <artifactId>embabel-agent-api</artifactId>
    <version>VERSION</version>
</dependency>

Streaming Not Working

Symptoms: Streaming requests return regular responses or errors

Solution 1: Ensure Accept header is set:

curl -H "Accept: text/event-stream" ...

Solution 2: Check method is streaming variant:

{
  "method": "message/stream",  // Not "message/send"
  ...
}

Solution 3: Verify SseEmitter timeout configuration:

@Configuration
class WebMvcConfig : WebMvcConfigurer {
    override fun configureAsyncSupport(configurer: AsyncSupportConfigurer) {
        configurer.setDefaultTimeout(Long.MAX_VALUE)
    }
}

Request Deserialization Errors

Symptoms:

Failed to deserialize request
JSONRPCErrorResponse with code 500

Solution: Verify request format matches A2A specification:

{
  "jsonrpc": "2.0",
  "id": "request-id",
  "method": "message/send",
  "params": {
    "message": {
      "messageId": "m1",
      "role": "user",
      "parts": [{"text": "..."}]
    }
  }
}

Task Not Found During Resubscription

Symptoms: IllegalArgumentException: Task not found: task-id

Causes:

Task was cleaned up (too old)
Task ID is incorrect
Server restarted (task state not persisted)

Solution: Check task exists before resubscribing:

if (taskStateManager.taskExists(taskId)) {
    val emitter = streamingHandler.resubscribeToTask(taskId, newStreamId)
} else {
    throw IllegalArgumentException("Task not found: $taskId")
}

Events Not Being Published

Symptoms: Event listeners not receiving A2ARequestEvent or A2AResponseEvent

Solution 1: Ensure @Component or @EventListener annotations:

@Component
class MyListener {
    @EventListener
    fun onRequest(event: A2ARequestEvent) { /* ... */ }
}

Solution 2: Check AgenticEventListener is configured in Embabel framework

Security Blocks AgentCard Access

Symptoms: 401/403 errors when accessing .well-known/agent.json

Solution: Allow public access to AgentCard endpoint:

@Configuration
@EnableWebSecurity
class SecurityConfig {
    @Bean
    fun filterChain(http: HttpSecurity): SecurityFilterChain {
        http.authorizeHttpRequests { auth ->
            auth
                .requestMatchers("/*/.well-known/agent.json").permitAll()
                .requestMatchers("/*/").authenticated()
        }
        return http.build()
    }
}

Context Path Issues

Symptoms: Endpoints expected at /a2a but actual path is /app/a2a

Cause: Application has context path configured:

server:
  servlet:
    context-path: /app

Solution: Endpoints are automatically at {context-path}/{handler-path}:

/app/a2a/.well-known/agent.json
/app/a2a

Update client URLs accordingly.

Goal Filter Returns No Goals

Symptoms: AgentCard has empty skills array

Solution: Verify goal filter logic:

// Debug: Log filtered goals
val filteredGoals = agentPlatform.goals.filter { goalFilter.invoke(it) }
logger.info("Filtered goals: {}", filteredGoals.map { it.name })

// Temporarily allow all goals to test
goalFilter = { true }

Memory Leaks from Task History

Symptoms: Increasing memory usage over time, especially with many streaming requests

Solution: Schedule periodic cleanup:

@Component
class TaskCleanup(private val taskStateManager: TaskStateManager) {

    @Scheduled(fixedRate = 3600000)  // Every hour
    fun cleanup() {
        val cutoff = Instant.now().minus(Duration.ofHours(24))
        taskStateManager.cleanupOldTasks(cutoff)
    }
}

Unsupported Method Errors

Symptoms:

UnsupportedOperationException: Method task/get is not supported
UnsupportedOperationException: Method task/cancel is not supported

Cause: These methods are not yet implemented in current version (0.3.3)

Implemented Methods:

✅ message/send - Synchronous messaging
✅ message/stream - Streaming messaging
✅ task/resubscribe - Resubscribe to existing task
❌ task/get - Not yet implemented
❌ task/cancel - Not yet implemented

Solution: Use implemented methods, or implement custom handler if needed.

tessl/maven-com-embabel-agent--embabel-agent-a2a